메뉴
编码前先创建 spec。用于开始新项目、功能或重大变更且还没有规格说明时。用于需求不清晰、有歧义，或只是一段模糊想法时。
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
| name | spec-driven-development |
| description | 编码前先创建 spec。用于开始新项目、功能或重大变更且还没有规格说明时。用于需求不清晰、有歧义，或只是一段模糊想法时。 |
在编写任何代码之前，先写一份结构化规格说明。spec 是你和人类工程师之间共享的事实来源，它定义我们要构建什么、为什么构建，以及如何知道它完成了。没有 spec 的代码就是猜测。
何时不要使用： 单行修复、拼写更正，或需求明确且自包含的变更。
Spec-driven development 有四个阶段。当前阶段被验证之前，不要进入下一阶段。
SPECIFY ──→ PLAN ──→ TASKS ──→ IMPLEMENT
│ │ │ │
▼ ▼ ▼ ▼
Human Human Human Human
reviews reviews reviews reviews
从高层愿景开始。向人类提出澄清问题，直到需求具体。
立即暴露假设。 在写任何 spec 内容之前，列出你的假设：
ASSUMPTIONS I'M MAKING:
1. This is a web application (not native mobile)
2. Authentication uses session-based cookies (not JWT)
3. The database is PostgreSQL (based on existing Prisma schema)
4. We're targeting modern browsers only (no IE11)
→ Correct me now or I'll proceed with these.
不要默默补全含糊需求。spec 的全部目的，就是在代码写出来之前暴露误解；假设是最危险的一种误解。
写一份覆盖这六个核心区域的 spec 文档：
Objective：我们在构建什么，为什么？用户是谁？成功是什么样子？
Commands：完整可执行命令，包含 flags，而不只是工具名。
Build: npm run build
Test: npm test -- --coverage
Lint: npm run lint --fix
Dev: npm run dev
Project Structure：源代码在哪里，测试放哪里，文档属于哪里。
src/ → Application source code
src/components → React components
src/lib → Shared utilities
tests/ → Unit and integration tests
e2e/ → End-to-end tests
docs/ → Documentation
Code Style：一个真实代码片段展示风格，胜过三段描述。包含命名约定、格式规则和优秀输出示例。
Testing Strategy：使用什么框架、测试放在哪里、覆盖率期望、哪些关注点对应哪些测试层级。
Boundaries：三层系统：
Spec 模板：
# Spec: [Project/Feature Name]
## Objective
[What we're building and why. User stories or acceptance criteria.]
## Tech Stack
[Framework, language, key dependencies with versions]
## Commands
[Build, test, lint, dev — full commands]
## Project Structure
[Directory layout with descriptions]
## Code Style
[Example snippet + key conventions]
## Testing Strategy
[Framework, test locations, coverage requirements, test levels]
## Boundaries
- Always: [...]
- Ask first: [...]
- Never: [...]
## Success Criteria
[How we'll know this is done — specific, testable conditions]
## Open Questions
[Anything unresolved that needs human input]
把指令重新框定为成功标准。 收到模糊需求时，把它们翻译成具体条件：
REQUIREMENT: "Make the dashboard faster"
REFRAMED SUCCESS CRITERIA:
- Dashboard LCP < 2.5s on 4G connection
- Initial data load completes in < 500ms
- No layout shift during load (CLS < 0.1)
→ Are these the right targets?
这样你就能围绕清晰目标进行循环、重试和解决问题，而不是猜测 “faster” 是什么意思。
在 spec 已验证后，生成技术实现计划：
计划应该可评审：人类读完后应该能说“对，这是正确做法”或“不，修改 X”。
把计划拆解为离散、可实现的任务：
任务模板：
- [ ] Task: [Description]
- Acceptance: [What must be true when done]
- Verify: [How to confirm — test command, build, manual check]
- Files: [Which files will be touched]
一次执行一个任务，并遵循 incremental-implementation 和 test-driven-development skills。使用 context-engineering 在每一步加载正确的 spec 章节和源文件，而不是把整个 spec 都塞给 agent。
spec 是一份活文档，不是一次性工件：
| 合理化借口 | 现实 |
|---|---|
| “这很简单，我不需要 spec” | 简单任务不需要长 spec，但仍然需要验收标准。两行 spec 可以。 |
| “我写完代码后再补 spec” | 那是文档，不是规格说明。spec 的价值在于在代码之前强制澄清。 |
| “spec 会拖慢我们” | 15 分钟 spec 可以避免数小时返工。15 分钟的 waterfall 胜过 15 小时的调试。 |
| “需求反正会变” | 这正是 spec 是活文档的原因。过时的 spec 仍然好过没有 spec。 |
| “用户知道自己想要什么” | 即使清晰请求也有隐含假设。spec 会暴露这些假设。 |
进入实现前，确认：
指导稳定的 API 和接口设计。设计 API、模块边界或任何公共接口时使用。创建 REST 或 GraphQL endpoint、定义模块之间的类型契约，或建立前后端边界时使用。
在真实浏览器中测试。构建或调试任何在浏览器中运行的内容时使用。当你需要通过 Chrome DevTools MCP 检查 DOM、捕获 console 错误、分析网络请求、分析性能，或用真实运行时数据验证视觉输出时使用。
自动化 CI/CD pipeline 设置。用于设置或修改构建和部署 pipeline 时；用于需要自动化质量门禁、在 CI 中配置 test runners，或建立部署策略时。
执行多维度代码审查。用于合并任何变更之前；用于审查自己、其他 agent 或人类编写的代码；用于在代码进入主分支前从多个维度评估代码质量。
为清晰度简化代码。用于在不改变行为的前提下重构代码以提升清晰度；用于代码能运行但比应有状态更难阅读、维护或扩展时；用于审查已累积不必要复杂度的代码时。
优化 agent 上下文设置。当开始新会话、agent 输出质量下降、在任务之间切换，或需要为项目配置规则文件和上下文时使用。