Advanced

Best Practices for spec-kit

Master specification writing, optimize AI prompts for better output, maintain living documents, adopt spec-kit across your team, and avoid common pitfalls.

Specification Writing Best Practices

🎯

Start with Why

Every spec should begin with the problem being solved and the business value. Context helps both humans and AI produce better content.

📏

Be Specific, Not Verbose

Use precise language and measurable criteria. "Fast response times" is vague; "API responds in under 200ms at p95" is actionable.

🔗

Link Related Specs

Cross-reference related PRDs, tech specs, and ADRs. spec-kit's related_prd field creates navigable connections.

⚠

Define Non-Goals

Explicitly state what is out of scope. This prevents scope creep and sets clear expectations with stakeholders.

AI Prompt Optimization for Specs

Get the most from spec-kit's AI generation by crafting effective context prompts:

Approach Poor Context Better Context
Feature description "Build a search feature" "Full-text search for e-commerce product catalog with faceted filtering, autocomplete, and typo tolerance using Elasticsearch"
Constraints "Make it fast" "Must return results in under 100ms, support 10K concurrent users, and work with 2M product records"
Audience (not specified) "Target audience: backend engineers implementing the search service. Assumes familiarity with Elasticsearch."
Terminal - Optimized AI Context 
# Provide rich context for better AI output
specc create prd --name "product-search" --ai \
  --context "Full-text product search for e-commerce
  platform. Tech stack: Node.js, Elasticsearch 8,
  Redis cache. Must support 2M products, faceted
  filtering by category/price/brand, autocomplete
  with typo tolerance. Target: 100ms p95 latency.
  Team: 3 backend engineers. Timeline: 6 weeks.
  Replaces current SQL LIKE-based search."

Maintaining Living Documents

Specifications that are not maintained become liabilities rather than assets. Follow these practices:

  1. Update Specs with Code Changes

    When implementation deviates from the spec, update the spec. Use specc validate --drift to detect discrepancies.

  2. Schedule Regular Reviews

    Set up quarterly spec reviews. Use specc audit --stale 90d to find specs that have not been updated in 90 days.

  3. Archive Completed Work

    Move delivered or superseded specs to the archive with specc archive. This keeps the active spec list manageable.

  4. Use Status Labels

    Keep the status field current: draft, review, approved, active, deprecated, archived.

Team Adoption Strategies

Successfully rolling out spec-kit across a team requires a thoughtful approach:

✅
Start small: Begin with one team or one spec type (e.g., ADRs). Demonstrate value before expanding to the whole organization. Mandating tools without buy-in leads to poor adoption.
  • Champion approach: Identify 1-2 spec champions per team who learn the tool deeply and mentor others.
  • Integrate into existing workflows: Add spec creation to your ticket workflow. Link specs to Jira tickets or GitHub issues.
  • Make it part of definition of done: Features are not complete until the spec reflects what was actually built.
  • Celebrate good specs: Highlight well-written specs in team meetings. Good documentation is a skill worth recognizing.
  • Lower the barrier: Use AI generation for first drafts. It is easier to edit than to write from scratch.

Common Pitfalls

⚠
Avoid these common mistakes that reduce the effectiveness of your specifications:
  • Over-specifying implementation: PRDs should describe what and why, not how. Leave implementation details to tech specs.
  • Blindly accepting AI output: Always review and customize AI-generated content. AI provides a starting point, not a finished product.
  • Writing specs after building: Specs written retroactively miss their primary purpose of guiding development.
  • Ignoring the audience: A PRD for stakeholders reads differently than a tech spec for engineers. Tailor language and detail level.
  • Treating specs as immutable: Specifications should evolve. Treat them as living documents, not contracts carved in stone.

Frequently Asked Questions

While spec-kit uses Markdown, it adds structure (YAML frontmatter for metadata), AI-powered generation, template systems, validation, review workflows, and export capabilities. Plain Markdown gives you formatting; spec-kit gives you a complete specification management system.

Yes. spec-kit exports to Confluence, Notion, PDF, HTML, and Markdown. You can use spec-kit as your authoring tool and sync to your existing documentation platform. Many teams use spec-kit for creation and review, then export to Confluence for broader visibility.

spec-kit supports Anthropic (Claude), OpenAI (GPT), and Google (Gemini) as AI providers. You can configure your preferred provider and model in config.yaml. The AI features work with any provider, though output quality may vary between models.

Absolutely. While spec-kit's collaboration features shine with teams, solo developers benefit from the AI-powered generation, templates, and structured approach to documentation. Writing specs before coding helps even individual developers think through problems more thoroughly.

spec-kit embraces change through its living document approach. Use the draft/review/active lifecycle, update specs each sprint, and leverage version history to track how requirements evolved. The specc validate --drift command helps identify specs that need updating.

spec-kit's AI features use external API providers (Anthropic, OpenAI, Google), so they require API access. However, you can use spec-kit's template, validation, and collaboration features entirely offline without any AI provider. For enterprise environments with data sensitivity requirements, configure the AI provider to use your organization's API endpoint.