很多 AI 编程请求只有一句话：
“这里优化一下。”
“把这个模块改得更好。”
“登录功能帮我加一下。”
问题不在于 AI 不会写代码，而在于这些说法可能对应多种完全不同的实现。spec-coding 会先检查项目现状，找出真正会改变实现结果的模糊点，再通过少量、有取舍说明的问题，把请求收敛成可实现、可测试、可确认的技术规格。
它不是一套沉重的 PRD 流程，也不会为了显得严谨而把每个小改动都变成需求访谈。
- 先查项目，再问用户：能从代码、配置、测试和现有文档中找到的答案，不重复询问。
- 只问关键分叉：只有不同答案会改变行为、接口、数据、安全、兼容性或验收方式时才提问。
- 最多五问，不要求问满：每次回答后重新判断；信息足够就立即停止。
- 帮助非技术用户做决定：把框架和底层术语翻译成结果、风险与取舍，并给出推荐选项。
- 明确就绪状态：使用
READY和NEEDS_DECISION区分“可以实施”与“仍有关键决策”。 - 确认后才改代码：先展示完整规格，用户确认后才进入实施。
flowchart LR
A[模糊的编码请求] --> B[检查项目现状]
B --> C{存在关键实现分叉?}
C -- 否 --> D[生成精简规格]
C -- 是 --> E[提出高影响问题]
E --> F{信息是否足够?}
F -- 否且未到5问 --> E
F -- 是 --> G[READY 规格]
F -- 5问后仍不明确 --> H[NEEDS_DECISION]
D --> I[展示给用户确认]
G --> I
I --> J[规划或实施]
| 模糊请求 | Spec Coding 关注的问题 | 可验收结果示例 |
|---|---|---|
| “优化一下接口” | 当前基准、目标延迟、负载、允许的数据新鲜度 | P95 延迟在指定负载下低于目标值，结果正确性不变 |
| “重构这个模块” | 重构目的、必须保持的行为、兼容边界 | 公共接口不变，现有回归测试全部通过 |
| “增加登录” | 身份来源、会话行为、保护范围、安全失败场景 | 未登录访问受保护页面时得到明确且可测试的结果 |
| “按钮改成蓝色” | 若目标和样式规范已明确，则不提问 | 指定按钮采用项目现有的蓝色设计令牌 |
-
点击仓库右上角的 Code → Download ZIP。
-
解压后，将文件夹重命名为
spec-coding。 -
把整个文件夹复制到：
Windows
%USERPROFILE%\.codex\skills\spec-codingmacOS / Linux
~/.codex/skills/spec-coding -
确认
SKILL.md直接位于spec-coding文件夹内，而不是多嵌套了一层目录。 -
重新打开 Codex 或开始一个新任务。
git clone https://github.com/Zyc20010326/spec-coding.git ~/.codex/skills/spec-coding显式调用：
$spec-coding 请先把“优化这个接口”收敛成可实施规格，再开始修改。
也可以直接提出模糊的编码请求。Skill 已允许选择性自动触发：明确、低风险的一步修改不会强制进入访谈。
输出规格会按任务需要选用以下内容，而不是机械填满模板：
- 目标与范围
- 当前状态与必须保持的行为
- 技术方案、接口和数据变化
- 异常与边界行为
- 性能、安全、兼容和迁移要求
- 验收场景、已确认决策和默认假设
READY：剩余未知不会实质改变实现或验收，可以交给开发者或编码代理执行。NEEDS_DECISION：最多五问后仍有关键分叉；Skill 会列出阻塞项和推荐方案，但不会假装需求已经明确。
spec-coding 适合功能开发、性能优化、重构、迁移、集成和其他存在实质歧义的编码任务。它不会：
- 替代完整的产品调研或架构评审；
- 强迫简单修改生成独立规格文件；
- 在用户确认前修改代码；
- 因为用户没指定框架，就无视项目现有技术栈重新选型。
Many AI coding requests begin with a single vague sentence:
“Optimize this.”
“Make this module better.”
“Add login.”
The problem is not whether the model can write code. The problem is that each request can lead to several valid—but incompatible—implementations. spec-coding inspects the project first, identifies only the ambiguities that materially affect the result, and turns them into a small number of decision-oriented questions.
The result is an implementation-ready, testable specification without forcing every small change through a heavyweight requirements process.
- Inspect before asking — derive answers from code, configuration, tests, and existing specifications whenever possible.
- Ask only consequential questions — clarify decisions that change behavior, interfaces, data, security, compatibility, or acceptance.
- Up to five questions, not five required — reassess after every answer and stop as soon as the request is sufficiently specified.
- Accessible to nontechnical users — translate technology choices into outcomes, risks, and tradeoffs, with a recommended option.
- Explicit readiness states — distinguish an actionable
READYspecification from unresolvedNEEDS_DECISIONwork. - Confirm before implementation — show the complete specification before modifying code.
- Inspect the minimum relevant repository context.
- Separate discoverable facts, safe defaults, user decisions, and irrelevant gaps.
- Rank unresolved decisions by impact, uncertainty, and irreversibility.
- Ask only the highest-value questions, stopping early when enough information is available.
- Produce a compact specification with a
READYorNEEDS_DECISIONstatus. - Wait for confirmation before planning or implementation continues.
Download this repository and place it at:
~/.codex/skills/spec-coding
On Windows, the equivalent location is:
%USERPROFILE%\.codex\skills\spec-coding
Make sure SKILL.md is directly inside that directory. Reopen Codex or start a new task after installation.
Alternatively:
git clone https://github.com/Zyc20010326/spec-coding.git ~/.codex/skills/spec-codingUse $spec-coding to clarify “optimize this endpoint” into an implementation-ready specification before making changes.
The skill also supports selective automatic invocation for materially ambiguous coding requests. Clear, low-risk, one-step changes should remain lightweight.
READY— no remaining unknown materially changes implementation or acceptance.NEEDS_DECISION— an important fork remains after the question ceiling; implementation must not begin yet.
spec-coding/
├── SKILL.md
├── README.md
├── agents/
│ └── openai.yaml
└── references/
└── readiness-model.md
The workflow is informed by established specification and clarification practices, including:
- GitHub Spec Kit — Agentic Spec-Driven Development
- Kiro Feature Specs
- HumanEvalComm: Benchmarking Communication Competence in Code Generation
- ClarifyCodeBench: Evaluating Clarification of Ambiguous Coding Requirements
Issues and pull requests are welcome. Useful contributions include realistic ambiguous coding requests, examples of unnecessary questions, missed implementation forks, and improvements to the readiness criteria.
Clear enough to build. Small enough to use.
足够明确，可以开工；足够轻量，愿意使用。