Spec Writer — Structured Implementation Spec Generator
Generate high-quality, AI-agent-friendly spec documents from vague requirements.
When to Use
- - User has a requirement, feature idea, bug report, or GitHub issue
- User wants a structured document before coding starts
- User says "write a spec", "plan this out", "spec this feature", etc.
- dev-workflow Phase 2 needs a detailed spec (can be called as a sub-step)
Output
A single Markdown spec document saved to the project directory (default: SPEC.md or spec/<name>.md).
Workflow
Step 1: Gather Context
Collect information from available sources. Do not ask the user for things you can find yourself.
From the user's input:
- - What to build and why
- Any explicit constraints or preferences
From the project (if accessible):
- - Tech stack (package.json, Cargo.toml, pyproject.toml, go.mod, etc.)
- Project structure (directory layout)
- Existing architecture docs (llmdoc/, README, ARCHITECTURE.md, etc.)
- Code style patterns (sample existing code)
- Test setup (test framework, where tests live, how to run them)
- Git workflow (branch conventions, CI config)
From external sources (if referenced):
- - GitHub issue details (title, body, comments, labels)
- Linked docs, designs, or API references
Step 2: Draft the Spec
Use the spec template at references/spec-template.md. Read it before generating.
Fill every section based on gathered context. Key principles:
- - Be specific, not vague. "React 18 with TypeScript and Vite" not "React project."
- Focus on what and why first. User stories and success criteria anchor everything.
- Include real commands. Full commands with flags, not just tool names.
- Show, don't describe. One code example beats three paragraphs of explanation.
- State what NOT to do. Explicit exclusions prevent agent drift.
- Use three-tier boundaries. ✅ Always / ⚠️ Ask first / 🚫 Never.
Step 3: Review with User
Present the draft to the user. Common discussion points:
- - Are the user stories complete? Any missing scenarios?
- Is the technical approach acceptable? Alternative architectures?
- Are boundaries correct? Anything too strict or too loose?
- Are verification criteria testable and sufficient?
- Is the task breakdown granularity right?
Revise until the user confirms. Mark status as "✅ Confirmed" when approved.
Step 4: Save and Deliver
Save the confirmed spec to the project. Suggested locations:
- - Single feature:
SPEC.md in project root - Multiple specs: INLINECODE4
- With dev-workflow: the spec replaces the requirement doc in Phase 2
Tell the user the spec is ready and suggest next steps:
- - Hand to a coding agent (dev-workflow, Claude Code, Codex, etc.)
- Use as a reference for manual implementation
- Share with team for review
Adapting to Project Scale
Small task (bug fix, small feature):
- - Skip or compress sections that don't apply
- Focus on: Objective, Changes, Boundaries, Verification
- Total spec: ~50-100 lines
Medium task (feature, refactor):
- - Use full template
- Total spec: ~100-250 lines
Large task (new module, major feature):
- - Use full template with extended task breakdown
- Consider splitting into multiple specs (one per component/module)
- Include architecture diagram description or data model
- Total spec: ~200-400 lines
Principles
These come from industry best practices (GitHub's study of 2,500+ agent files, Anthropic's context engineering research, and practical spec-driven development patterns):
- 1. Spec is the source of truth — It persists across sessions, anchoring the agent when context gets long or sessions restart.
- 2. Structure for parseability — Clear Markdown headings, consistent format. AI models handle well-structured text better than free-form prose.
- 3. Six core areas — Commands, Testing, Project Structure, Code Style, Git Workflow, Boundaries. Use as a completeness checklist.
- 4. Three-tier boundaries — ✅ Always do (proceed without asking) / ⚠️ Ask first (need human approval) / 🚫 Never do (hard stop). More effective than flat rule lists.
- 5. Modularity — Each section should be independently useful. A coding agent working on the backend doesn't need the frontend spec section in its context.
- 6. Living document — Update the spec when decisions change. An outdated spec is worse than no spec.
规范编写器 — 结构化实现规范生成器
从模糊需求生成高质量、对AI智能体友好的规范文档。
使用时机
- - 用户有需求、功能想法、Bug报告或GitHub Issue
- 用户希望在编码开始前获得结构化文档
- 用户提出写一份规范、规划这个、为这个功能写规范等要求
- 开发工作流的第二阶段需要详细规范（可作为子步骤调用）
输出
一份保存到项目目录的Markdown规范文档（默认路径：SPEC.md 或 spec/<名称>.md）。
工作流程
第一步：收集上下文
从可用来源收集信息。不要询问用户你自己能找到的内容。
来自用户的输入：
来自项目（如可访问）：
- - 技术栈（package.json、Cargo.toml、pyproject.toml、go.mod等）
- 项目结构（目录布局）
- 现有架构文档（llmdoc/、README、ARCHITECTURE.md等）
- 代码风格模式（现有代码示例）
- 测试设置（测试框架、测试存放位置、运行方式）
- Git工作流（分支约定、CI配置）
来自外部来源（如被引用）：
- - GitHub Issue详情（标题、正文、评论、标签）
- 关联文档、设计稿或API参考
第二步：起草规范
使用 references/spec-template.md 中的规范模板。生成前先阅读该模板。
根据收集到的上下文填写每个部分。关键原则：
- - 具体明确，而非模糊不清。 使用React 18 with TypeScript and Vite而非React项目。
- 先关注是什么和为什么。 用户故事和成功标准是一切的基础。
- 包含真实命令。 提供带参数标志的完整命令，而不仅仅是工具名称。
- 展示而非描述。 一个代码示例胜过三段解释文字。
- 明确说明不要做什么。 明确的排除项可防止智能体偏离方向。
- 使用三级边界。 ✅ 始终执行 / ⚠️ 先询问 / 🚫 绝不执行。
第三步：与用户评审
向用户展示草稿。常见讨论点：
- - 用户故事是否完整？是否有遗漏的场景？
- 技术方案是否可接受？是否有替代架构？
- 边界是否正确？是否有任何限制过严或过松？
- 验证标准是否可测试且充分？
- 任务分解粒度是否合适？
根据用户反馈进行修订，直到用户确认。批准后将状态标记为✅ 已确认。
第四步：保存并交付
将确认后的规范保存到项目中。建议位置：
- - 单个功能：项目根目录下的 SPEC.md
- 多个规范：spec/<功能名称>.md
- 配合开发工作流：规范替换第二阶段的需求文档
告知用户规范已就绪，并建议后续步骤：
- - 交给编码智能体（开发工作流、Claude Code、Codex等）
- 作为手动实现的参考
- 与团队分享进行评审
根据项目规模调整
小型任务（Bug修复、小功能）：
- - 跳过或压缩不适用的部分
- 聚焦于：目标、变更、边界、验证
- 规范总长度：约50-100行
中型任务（功能、重构）：
大型任务（新模块、主要功能）：
- - 使用完整模板并扩展任务分解
- 考虑拆分为多个规范（每个组件/模块一个）
- 包含架构图描述或数据模型
- 规范总长度：约200-400行
原则
这些原则源自行业最佳实践（GitHub对2500+智能体文件的研究、Anthropic的上下文工程研究以及实践中的规范驱动开发模式）：
- 1. 规范是唯一真相来源 — 它在不同会话间持久存在，当上下文变长或会话重启时，为智能体提供锚定。
- 2. 结构便于解析 — 清晰的Markdown标题、一致的格式。AI模型处理结构良好的文本比处理自由形式的散文效果更好。
- 3. 六大核心领域 — 命令、测试、项目结构、代码风格、Git工作流、边界。用作完整性检查清单。
- 4. 三级边界 — ✅ 始终执行（无需询问直接进行）/ ⚠️ 先询问（需要人工批准）/ 🚫 绝不执行（硬性停止）。比扁平规则列表更有效。
- 5. 模块化 — 每个部分应能独立使用。负责后端的编码智能体不需要在其上下文中包含前端规范部分。
- 6. 活文档 — 当决策发生变化时更新规范。过时的规范比没有规范更糟糕。
