Skip to main content

Frequently Asked Questions

Getting Started​

What is HarnSpec?​

HarnSpec is a lightweight spec framework optimized for AI-assisted development. It's a CLI tool + markdown files that live in your repo, helping you document technical decisions and guide AI coding tools while keeping specs within the 2,000-token sweet spot for optimal performance.

Key features:

  • Numbered specs for easy reference
  • CLI tools for creating, searching, and managing specs
  • Agent Skills for AI tool integration (GitHub Copilot, Claude Code, Cursor, etc.)
  • Validation to ensure spec quality
  • Kanban board and stats for project visibility

5-minute setup:

npm install -g harnspec
cd your-project
harnspec init
harnspec create my-first-spec

No configuration files, no database, no server. Works with any editor and any AI tool.

How do I get started with HarnSpec?​

This is the most common question! Here's your quickstart path:

Option 1: Try with tutorial project (recommended for first-timers)

npx harnspec init --example dark-theme
cd dark-theme && npm install && npm start

Option 2: Add to existing project

npm install -g harnspec
cd your-project
harnspec init
harnspec create my-first-feature

After setup:

  1. Run harnspec board to see the Kanban view
  2. Edit your spec at specs/001-my-first-feature/README.md
  3. Run harnspec update 001 --status in-progress when you start coding
  4. Run harnspec update 001 --status complete when done

Next steps:

Why use HarnSpec?​

Use HarnSpec when you need:

  • Team alignment on complex features
  • Documentation for design decisions
  • Context to reduce AI hallucinations
  • Onboarding materials for new team members

Skip HarnSpec for:

  • Simple bug fixes
  • Throwaway prototypes
  • Solo projects with clear requirements

Philosophy: Get 80% of vibe coding speed with 80% of structured spec benefits. Minimal overhead for maximum agility.

Can HarnSpec speed up my development?​

Yes, but with nuance. HarnSpec isn't about typing faster—it's about reducing rework and improving AI output quality.

How it speeds up development:

  1. Better AI output - Specs provide focused context (<2,000 tokens) that AI models process more accurately than scattered conversation history
  2. Less rework - Clear requirements upfront = fewer "that's not what I wanted" cycles
  3. Faster onboarding - New team members (or AI assistants) understand decisions immediately
  4. Reduced context rot - AI doesn't hallucinate when it has written specs to reference

Real-world impact:

  • Single implementation attempts succeed more often (vs. 3-4 back-and-forth cycles)
  • Less time explaining the same decisions repeatedly
  • Team alignment happens once, not every sprint

When HarnSpec might slow you down:

  • Simple bug fixes (skip the spec, just fix it)
  • Throwaway prototypes (vibe coding is faster)
  • Very clear, well-understood work

The formula: Time saved = (AI rework avoided) + (team sync avoided) - (spec writing time)

For complex features, this is almost always positive. For trivial changes, skip the spec.

Why the 2,000-token target?​

Attention is the scarce resource, not storage.

Three reasons:

  1. Human attention span - Most people (and AI pairs) can only hold ~2-3K tokens in working memory at once
  2. AI performance - Context quality degrades long before the 50K-token hard limit
  3. Working memory - Token count correlates directly to cognitive load, while lines vary by formatting

If your spec exceeds 3,500 tokens, split it into sub-spec files (DESIGN.md, IMPLEMENTATION.md, TESTING.md, etc.). Anything above 5,000 tokens should be broken down immediately. See First Principles for details.

Comparisons​

What's the difference between HarnSpec and other SDD frameworks?​

HarnSpec vs Spec Kit vs OpenSpec:

AspectHarnSpecSpec KitOpenSpec
PhilosophyLightweight, flexibleStructured governanceFormal proposals
Spec size<2,000 tokens (optimized)Longer contextLong system prompts
WorkflowFlexible, adapt to team5-step required processProposal→Review→Archive
TemplatesMinimal, customizableRigid formatRigid delta format
AI integrationAgent Skills + CLISlash commandsSlash commands
Visual UI✅ Yes❌ CLI only❌ CLI only
Best forTeams wanting agilityEnterprise governanceFormal change tracking

Key HarnSpec advantages:

  • Context Economy - Optimized for AI working memory
  • Editor-agnostic - Works with any AI tool (Copilot, Claude, Cursor, etc.)
  • Low cognitive load - Start simple, grow as needed
  • Visual mode - Web UI for browsing and presenting specs

When to choose alternatives:

  • Spec Kit: Enterprise teams needing structured 5-step governance
  • OpenSpec: Teams wanting formal proposal/review workflows
  • Kiro: Teams wanting an integrated AI IDE (but with vendor lock-in)

📖 Full comparison with detailed analysis →

The 2,000-token limit is based on cognitive science and AI attention research—it helps all models, not just Claude.

How do I integrate HarnSpec with AI tools like Claude Code?​

Quick setup (2 minutes):

  1. Run harnspec init to create the AGENTS.md and SKILL.md (via harnspec skill install).
  2. These files provide the necessary instructions for AI agents to use the harnspec CLI.
  3. Most modern AI agents (like Claude Code) can discover and use CLI tools automatically if they are told about them.

Test it:

List all specs in this project using the harnspec CLI.

HarnSpec works best when the AI agent uses the CLI for semantic search, dependency tracking, and more.

📖 Agent Configuration guide →

Why doesn't my AI agent follow the HarnSpec workflow?​

Common causes and fixes:

1. No AGENTS.md file

AI agents need explicit instructions. Create AGENTS.md at your project root:

harnspec init  # Creates AGENTS.md automatically

Or copy from: AGENTS.md template

2. AGENTS.md not in context

AI tools have different ways of loading project files:

  • VS Code Copilot: Add @workspace to include project files
  • Claude Code: Auto-loads AGENTS.md via Agent Skills
  • Cursor: Uses .cursorrules (copy AGENTS.md content there)

3. Instructions too long

If AGENTS.md is too long, AI may ignore parts. Keep it under 2,000 tokens.

4. Conflicting instructions

Check for other instruction files that might conflict:

  • .github/copilot-instructions.md
  • .cursorrules
  • System prompts in Agent Skills config

5. AI doesn't have CLI access

Ensure your AI tool is allowed to run shell commands or has the harnspec binary in its PATH.

Debugging tip: Ask the AI directly:

What instructions do you have about HarnSpec workflow?
Can you list the specs in this project?

📖 Agent configuration guide →

Using HarnSpec​

How do I upgrade or re-initialize HarnSpec without losing my specs?​

HarnSpec has safe re-initialization built in. You don't need to delete anything manually.

Scenario 1: Upgrade to latest config (safest)

harnspec init -y

This merges your existing config with latest defaults. All specs and AGENTS.md are preserved.

Scenario 2: Reset config but keep specs

harnspec init -f

This resets .harnspec/ configuration but keeps your specs/ directory intact.

Scenario 3: Interactive choice

harnspec init

When HarnSpec is already initialized, you'll see options:

  • Upgrade configuration (recommended) - Update config, keep everything
  • Reset configuration - Fresh config, keep specs
  • Full reset - Start completely fresh (requires confirmation)
  • Cancel - Exit without changes

What each option preserves:

Option.harnspec/specs/AGENTS.md
UpgradeMerged✅ Kept✅ Kept
Reset configFresh✅ KeptRe-created
Full resetDeleted❌ Deleted❌ Deleted

Pro tip: Always use -y for CI/CD pipelines - it defaults to the safest upgrade option.

How do I view the HarnSpec UI?​

Start the web UI:

harnspec ui

This opens a browser at http://localhost:3000 with:

  • Spec browser - Browse and search all specs
  • Board view - Kanban-style visualization
  • Dependency graph - Visual relationships between specs
  • Project stats - Dashboard with metrics

Alternative method (no CLI installation):

npx @HarnSpec/ui

Options:

harnspec ui --port 3100    # Custom port
harnspec ui --no-open      # Don't auto-open browser
harnspec ui --specs ./path # Custom specs directory

📖 Visual Mode guide →

How do I use HarnSpec to manage multiple features?​

HarnSpec excels at managing concurrent development:

1. Create specs for each feature:

harnspec create user-auth --tags auth,api --priority high
harnspec create payment-flow --tags payments,api --priority high
harnspec create dashboard --tags frontend,ui --priority medium

2. Track relationships:

# Dashboard depends on auth being complete
harnspec link dashboard --depends-on user-auth

3. Visualize progress:

harnspec board          # Kanban view
harnspec stats          # Project metrics
harnspec deps dashboard # See what's blocking dashboard

4. Filter by status or tags:

harnspec list --status in-progress    # What's being worked on?
harnspec list --tag api               # All API-related specs
harnspec list --assignee @alice       # Alice's work

5. Use the UI for team visibility:

harnspec ui
# Share http://localhost:3000 in team meetings

Best practices for multiple features:

  • Use tags consistently (api, frontend, backend, etc.)
  • Set priorities (critical, high, medium, low)
  • Update status religiously (planned → in-progress → complete)
  • Use depends_on only for true blockers
  • Document other relationships in spec content

How do I deal with bugs in completed specs?​

Bugs in implemented features need different handling based on severity:

Option 1: Minor bug (quick fix)

Don't create a new spec. Just fix it:

# No spec needed for simple bug fixes
git commit -m "fix: handle null user in auth flow (spec-042)"

Reference the original spec in commit message for traceability.

Option 2: Significant bug (design flaw)

Create a follow-up spec:

harnspec create auth-token-refresh-fix --tags auth,bugfix --priority high

Link to original:

harnspec link auth-token-refresh-fix --depends-on user-auth

In the new spec, document:

  • What went wrong in the original implementation
  • Root cause analysis
  • Updated design decision

Option 3: Update the original spec

If the bug reveals a missing requirement:

harnspec open user-auth
# Add "Lessons Learned" section documenting the issue
# Update relevant sections with corrected approach

When to use each option:

Bug TypeAction
Typo, off-by-oneJust fix it (no spec)
Missing edge caseAdd to original spec
Design flawNew follow-up spec
Breaking changeNew spec with migration plan

Key principle: Specs document decisions, not code. If the decision was wrong, update the spec. If the implementation was wrong, just fix the code.

Troubleshooting​

My spec was corrupted by AI editing it​

Cause: Spec exceeded context window, AI lost track of structure.

Fix:

git checkout HEAD -- specs/042-my-spec/  # Restore from git
harnspec validate                        # Check for issues

Prevention: Keep specs under 2,000 tokens (warning at 3,500, hard stop at 5,000). Run harnspec tokens <spec> to check before editing.

harnspec update says "spec not found"​

Debug:

harnspec list          # See all active specs
harnspec list --all    # Include archived

Common causes:

  • Not in git repo with specs/ directory
  • Typo in spec name/number
  • Spec was archived

Frontmatter validation failed​

Common mistakes:

  • Manually editing system-managed fields (status, created_at, transitions, etc.)
  • Invalid YAML syntax
  • Typos in field names

Fix:

harnspec validate      # See exactly what's wrong

Always use CLI commands to update metadata:

harnspec update 042 --status in-progress
harnspec update 042 --priority high
harnspec update 042 --tags api,backend

How do I recover deleted specs?​

Specs are just files in git:

git log --all --full-history -- "specs/042-my-spec/*"
git checkout <commit> -- specs/042-my-spec/

Or restore from archived:

mv archived/042-my-spec specs/
harnspec update 042 --status in-progress

CLI command not working​

Check installation:

which harnspec
harnspec --version

Reinstall if needed:

npm install -g harnspec

Verify you're in a git repo:

git rev-parse --git-dir

Contributing & Support​

How do I report bugs or request features?​

Can I contribute?​

Yes! See CONTRIBUTING.md.

Common contributions:

  • Documentation improvements
  • Bug fixes
  • New templates
  • CLI tool enhancements

Where can I get help?​

What's the license?​

MIT License - free for commercial and personal use.

More questions? Check the full documentation or ask in GitHub Discussions.