issue-spec

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

issue-spec

Create GitHub issues as lean-spec style specifications for human-AI aligned implementation on whatever repo this skill is installed in. GitHub issues are the sole spec medium — no spec files.

This skill is the repo-agnostic methodology half of the contract. Each consumer repo overlays its own delta in two places:

Repo CLAUDE.md — names the GitHub slug (
```
codervisor/lean-spec
```
,
```
onsager-ai/onsager
```
,
```
onsager-ai/duhem
```
, …) and any repo-specific spec principles (e.g. Onsager's Reach + seam rule, lean-spec's provider-agnostic core + i18n, Duhem's worked-example + schema-impact).
Sister skills —
```
<repo>-dev-process
```
carries the area-label taxonomy, the spec-vs-
```
trivial
```
gate, and the SDD loop wiring;
```
<repo>-pre-push
```
carries pre-push gates;
```
<repo>-pr-lifecycle
```
carries the post-push workflow (including any
```
pr-spec-sync
```
automation or the lack of it).

When in doubt about the target repo, run

git remote -v

and read the repo's

CLAUDE.md

and its

*-dev-process

skill before drafting the spec body.

在当前安装此技能的仓库中，创建lean-spec风格的GitHub Issue作为人机对齐实现的规范。GitHub Issue是唯一的规范载体——无需单独的规范文件。

此技能是协议中与仓库无关的方法论部分。每个使用此技能的仓库会通过两处内容添加自身的定制规则：

仓库的CLAUDE.md —— 指定GitHub仓库标识（如
```
codervisor/lean-spec
```
、
```
onsager-ai/onsager
```
、
```
onsager-ai/duhem
```
等）以及任何仓库特定的规范原则（例如Onsager的Reach + 衔接规则、lean-spec的供应商无关核心 + 国际化、Duhem的示例实践 + 架构影响）。
姐妹技能 ——
```
<repo>-dev-process
```
包含领域标签分类、规范与
```
trivial
```
（指微小改动）的判定标准，以及SDD循环流程；
```
<repo>-pre-push
```
包含推送前的检查规则；
```
<repo>-pr-lifecycle
```
包含推送后的工作流（包括是否有
```
pr-spec-sync
```
自动化机制）。

如果对目标仓库存疑，请先执行

git remote -v

命令，并阅读仓库的

CLAUDE.md

及其

*-dev-process

技能，再起草规范正文。

Why GitHub Issues, Not Files

为何选择GitHub Issue而非文件

lean-spec uses Markdown files with YAML frontmatter for metadata. We replace that entirely with GitHub issues because:

Status → Issue state (open/closed) + status labels (
```
draft
```
,
```
planned
```
,
```
in-progress
```
)

Priority → Labels (

priority:critical

priority:high

priority:medium

priority:low

)

Tags → Labels (
```
area:<subsystem>
```
,
```
feat
```
,
```
fix
```
,
```
refactor
```
,
```
perf
```
)
Dependencies → Issue references (
```
depends on #42
```
) and sub-issues
Parent/Child → Sub-issues via
```
mcp__github__sub_issue_write
```
Transitions → Issue timeline (automatic, auditable)
Collaboration → Comments, reactions, assignments, mentions

GitHub gives us versioned metadata, collaboration, and relationship tracking for free. No CLI needed, no frontmatter to manage, no sync problems.

lean-spec原本使用带YAML前置元数据的Markdown文件。我们完全改用GitHub Issue，原因如下：

状态 → Issue状态（打开/关闭）+ 状态标签（
```
draft
```
、
```
planned
```
、
```
in-progress
```
）

优先级 → 标签（

priority:critical

、

priority:high

、

priority:medium

、

priority:low

）

标签 → 标签（
```
area:<subsystem>
```
、
```
feat
```
、
```
fix
```
、
```
refactor
```
、
```
perf
```
）
依赖关系 → Issue引用（
```
depends on #42
```
）和子Issue
父/子关系 → 通过
```
mcp__github__sub_issue_write
```
创建子Issue
状态流转 → Issue时间线（自动生成、可审计）
协作 → 评论、反应、任务分配、提及

GitHub免费为我们提供了版本化元数据、协作功能和关系追踪。无需CLI工具，无需管理前置元数据，无同步问题。

Philosophy

理念

Three principles from lean-spec, universal across consumer repos:

Context Economy — Keep issue body under ~2000 tokens. Larger features split into parent + child issues. Small specs produce better AI output and better human review.
Intent Over Implementation — Document the why and what, not the how. Implementation details belong in PRs, not spec issues. The spec captures human intent that isn't in the code.
Living Documents — Specs evolve via issue comments and edits. Status labels track lifecycle. The issue thread becomes the decision record.

Each consumer repo may add 1–2 repo-specific principles on top — read the repo's

CLAUDE.md

and its

*-dev-process

sister skill before drafting. Examples of overlay principles you'll find in the wild:

Reach ships with the primitive (Onsager) — new user-facing primitives must scope in nav entry, first-run flow, empty-state CTAs, and auth gating; deferring discoverability is the bad call.
Provider-agnostic core + i18n (lean-spec) — changes to the provider abstraction declare
```
## Provider impact
```
; user-visible strings land in both
```
en
```
and
```
zh-CN
```
.
Worked example + schema impact (Duhem) — product-surface specs ship with a minimal Verification Definition that exercises the surface; schema-touching changes declare
```
## Schema impact
```
.

If the overlay introduces an additional issue-body section or label (e.g.

Provider impact

Schema impact

provider-impact

schema-impact

i18n

), apply it. The repo's CLAUDE.md or sister skill is authoritative for which extras it requires.

lean-spec的三大通用原则，适用于所有使用此技能的仓库：

上下文精简 —— Issue正文控制在约2000 tokens以内。大型功能拆分为父Issue + 子Issue。短小的规范能产生更优质的AI输出和人工评审结果。
重意图而非实现 —— 记录“为什么”和“做什么”，而非“怎么做”。实现细节属于PR，而非规范Issue。规范要捕捉代码中未体现的人类意图。
活文档 —— 规范通过Issue评论和编辑不断演进。状态标签追踪生命周期。Issue线程成为决策记录。

每个使用此技能的仓库可能会额外添加1-2条仓库特定原则——起草前请阅读仓库的

CLAUDE.md

及其

*-dev-process

姐妹技能。实际场景中常见的附加原则示例：

Reach随原语一同交付（Onsager）—— 新的用户面向原语必须包含导航入口、首次运行流程、空状态CTA和权限控制；延迟可发现性是错误选择。
供应商无关核心 + 国际化（lean-spec）—— 对供应商抽象的变更需声明
```
## Provider impact
```
；用户可见字符串需同时支持
```
en
```
和
```
zh-CN
```
。
示例实践 + 架构影响（Duhem）—— 产品界面规范需附带最小化验证定义以验证界面；涉及架构的变更需声明
```
## Schema impact
```
。

如果附加原则引入了额外的Issue正文章节或标签（如

Provider impact

、

Schema impact

、

provider-impact

、

schema-impact

、

i18n

），请应用它们。仓库的CLAUDE.md或姐妹技能是这些额外要求的权威来源。

When to use this skill

何时使用此技能

Use when:

A change touches multiple files or subsystems.
Multiple stakeholders need alignment before implementation.
The AI needs explicit boundaries for a non-trivial feature.
Work will span multiple PRs (parent + child specs).
The change touches an externally observable contract — schema, CLI surface, public API, provider trait, event manifest — regardless of diff size. Consumer repos may name additional always-spec surfaces in their CLAUDE.md or sister skill; honour them.

Skip when:

A typo or doc-only fix. Use the
```
trivial
```
label on the PR instead.
A one-line bug fix with an obvious reproduction. Just open a PR with
```
Fixes #existing
```
.
The feature already has a spec issue — extend that spec, don't create another.

Default is spec, not trivial. If invocation of this skill is itself the decision — the user said "spec this" or the change clearly isn't a typo/one-liner — proceed straight to Discover. Do not stop to confirm spec-vs-

trivial

. The "Skip when" list is a self-veto for unambiguously trivial diffs; everything else is a spec by default.

trivial

is a sparingly-used escape hatch (see the repo's

*-dev-process

and

*-pre-push

sister skills), not a 50/50 fork to ask about.

在以下场景使用：

变更涉及多个文件或子系统。
多个利益相关方需要在实现前达成对齐。
AI需要明确的非平凡功能边界。
工作将跨越多个PR（父规范 + 子规范）。
变更涉及外部可见的契约——架构、CLI界面、公共API、供应商特性、事件清单——无论代码差异大小。使用此技能的仓库可能会在其CLAUDE.md或姐妹技能中指定其他必须制定规范的场景，请予以遵守。

以下场景跳过使用：

拼写错误或仅修改文档的修复。在PR上使用
```
trivial
```
标签即可。
一行代码的Bug修复，且复现步骤明确。直接打开PR并标注
```
Fixes #existing
```
。
该功能已有规范Issue——扩展现有规范，无需创建新的。

默认需制定规范，而非标记为trivial。如果调用此技能本身就是决策——用户说“spec this”或变更显然不是拼写错误/一行代码修改——直接进入Discover阶段。除非主题确实模糊，否则不要询问澄清问题——也不要询问是否应将变更标记为

trivial

的PR。调用此技能即代表决策；上述“跳过场景”列表仅用于明确判定为微小变更的自我否决；其他所有场景默认需制定规范。

trivial

是极少使用的例外（请参考仓库的

*-dev-process

和

*-pre-push

姐妹技能），而非需要询问的二选一选项。

Setup

设置

Parameter	Default	Example override
Topic	(required)	`"session timeout"` , `"fix heartbeat race"`
Scope	Inferred from codebase	`"only stiglab"` , `"only the cli"`
Priority	`medium`	`critical` , `high` , `low`
Labels	Auto from type + area	`"spec, feat, area:<sub>"`
Parent	None	`#42` (umbrella issue)

If the user says "spec session timeout", start immediately. Do not ask clarifying questions unless the topic is genuinely ambiguous — and do not ask whether the change should be a

trivial

-labeled PR instead. Invocation of this skill is the decision; the "Skip when" list above is the only place that question gets re-litigated, and only for unambiguously trivial diffs.

参数	默认值	示例覆盖值
Topic	(必填)	`"session timeout"` , `"fix heartbeat race"`
Scope	从代码库推断	`"only stiglab"` , `"only the cli"`
Priority	`medium`	`critical` , `high` , `low`
Labels	根据类型和领域自动生成	`"spec, feat, area:<sub>"`
Parent	无	`#42` （总览Issue）

如果用户说“spec session timeout”，请立即开始。除非主题确实模糊，否则不要询问澄清问题——也不要询问是否应将变更标记为

trivial

的PR。调用此技能即代表决策；上述“跳过场景”列表是唯一重新审视该问题的地方，且仅适用于明确的微小变更。

Workflow

工作流

1. Discover     Search existing issues and codebase
2. Design       Draft the spec issue body
3. Align        Partition human decisions vs AI work
4. Validate     Self-check before creating
5. Publish      Create GitHub issue (+ sub-issues if splitting)

1. Discover     搜索现有Issue和代码库
2. Design       起草规范Issue正文
3. Align        划分人类决策与AI工作范围
4. Validate     创建前自我检查
5. Publish      创建GitHub Issue（如需拆分则创建子Issue）

1. Discover

Before writing anything, understand what exists:

Search existing GitHub issues on the target repo for related or duplicate specs.
Grep the codebase for types, functions, modules related to the topic.
Read key files that will be affected.
Check git log for recent changes in the area.
Read the repo's
```
CLAUDE.md
```
and any canonical product doc it points at (e.g. an architecture doc, an ADR, a
```
docs/<product>-spec.md
```
) — they ground the spec in existing commitments and identify always-spec surfaces.

If a related spec issue already exists, reference it — don't duplicate.

在撰写任何内容前，先了解现有内容：

在目标仓库的GitHub上搜索相关或重复的规范Issue。
在代码库中搜索与主题相关的类型、函数、模块。
阅读将受影响的关键文件。
查看该领域的近期Git提交记录。
阅读仓库的
```
CLAUDE.md
```
及其指向的任何标准产品文档（如架构文档、ADR、
```
docs/<product>-spec.md
```
）——这些内容将规范与现有承诺绑定，并确定必须制定规范的场景。

如果已有相关规范Issue，请引用它——不要重复创建。

2. Design

Read references/spec-format.md for the section-by-section format guide.

Don't hard-wrap prose, list items, or blockquote lines. GitHub renders issue and comment bodies with

breaks: true

— every newline inside a paragraph, list item, or blockquote becomes a

<br>

, producing visible mid-sentence breaks. Source files in many repos wrap at ~70–100 columns; issue bodies must not. Each paragraph, list item, and blockquote line is a single long line; only blank lines separate paragraphs, and each new bullet/quote line starts on its own line. Fenced code blocks and tables preserve formatting and are unaffected. Headings are single-line by markdown's own rules.

Draft the issue body using the lean-spec structure:

markdown

undefined

阅读references/spec-format.md获取分章节格式指南。

不要对散文、列表项或引用行进行硬换行。GitHub渲染Issue和评论正文时使用

breaks: true

——段落、列表项或引用内的每个换行都会变成

<br>

，导致句子中途出现可见换行。许多仓库的源文件会在约70-100列处换行；Issue正文绝对不能这样做。每个段落、列表项和引用行都是单行长文本；仅用空行分隔段落，每个新的项目符号/引用行单独起一行。围栏代码块和表格保留格式，不受影响。标题根据Markdown规则本身就是单行的。

使用lean-spec结构起草Issue正文：

markdown

undefined

Overview

Problem statement and motivation. Why does this matter?

问题陈述和动机。为什么这很重要？

Design

Technical approach: data flow, API changes, architecture decisions. Keep it high-level — intent, not implementation.

技术方案：数据流、API变更、架构决策。保持高层次——注重意图，而非实现细节。

Plan

Checklist of concrete deliverables
Each item independently verifiable
Order reflects implementation sequence

具体交付项清单
每个项可独立验证
顺序反映实现流程

Test

How to verify each plan item
Include: unit tests, integration tests, manual checks

如何验证每个计划项
包括：单元测试、集成测试、人工检查

Notes

Tradeoffs, context, references. Optional — omit if empty.


Consumer repos may require additional sections (e.g. `## Provider impact`, `## Schema impact`, `## Worked example`) — read the repo's CLAUDE.md / sister skill for the full list and the rules for when each section is required vs. optional. Templates under [templates/](templates/issue-spec-template.md) cover the universal shape; consumer-repo overlays may extend the template.

**Context economy check**: If the issue body exceeds ~2000 tokens, split it:

- Create a parent issue with Overview + high-level Plan
- Create child issues (sub-issues), one per independent concern
- Each child has its own Design, Plan, Test sections
- Link children to parent via `mcp__github__sub_issue_write`

权衡、上下文、参考资料。可选——为空则省略。


使用此技能的仓库可能要求额外章节（如`## Provider impact`、`## Schema impact`、`## Worked example`）——请阅读仓库的CLAUDE.md/姐妹技能获取完整列表及各章节的必填/可选规则。[templates/](templates/issue-spec-template.md)下的模板涵盖通用结构；仓库定制规则可能会扩展模板。

**上下文精简检查**：如果Issue正文超过约2000 tokens，请拆分：

- 创建包含Overview + 高层次Plan的父Issue
- 创建子Issue（子任务），每个子Issue对应一个独立关注点
- 每个子Issue有自己的Design、Plan、Test章节
- 通过`mcp__github__sub_issue_write`将子Issue链接到父Issue

3. Align

Add an Alignment section to the issue body (this extends lean-spec for human-AI collaboration):

markdown

undefined

在Issue正文中添加Alignment章节（这是lean-spec针对人机协作的扩展）：

markdown

undefined

Alignment

Human decides

Architectural tradeoffs, scope, UX, go/no-go

架构权衡、范围、用户体验、是否推进

AI implements

Concrete code tasks tied to Plan items

与计划项绑定的具体代码任务

Open questions

Items that block AI implementation until a human decides


**Rules:**

- Every Plan item maps to either "Human decides" or "AI implements"
- If an item requires both, split it — the decision part is human, the execution is AI
- Open questions use `>` blockquotes so they're visually distinct
- Once a human answers a question (via issue comment), update the Alignment section

这些问题需人类决策后，AI才能继续实现


**规则**：

- 每个计划项要么属于“Human decides”，要么属于“AI implements”
- 如果一个项同时需要两者，请拆分——决策部分由人类完成，执行部分由AI完成
- 未解决问题使用`>`引用块，使其视觉上更突出
- 一旦人类通过Issue评论回答了问题，请更新Alignment章节

4. Validate

Before creating the issue, self-check:

Body is under ~2000 tokens (context economy)
Prose paragraphs, list items, and blockquote lines are not hard-wrapped (each is one long line; blank line between paragraphs, new bullet/quote line on its own)
Overview explains why, not just what
Design captures intent, not implementation details
Plan items are concrete and independently verifiable
Test items map to Plan items
Any repo-specific required section (e.g.
```
## Provider impact
```
,
```
## Schema impact
```
) is present, or the spec provably doesn't touch that surface
Human/AI boundaries are explicit — no "figure it out" items
No duplicate of an existing issue
Dependencies are referenced by issue number

在创建Issue前，进行自我检查：

正文在约2000 tokens以内（上下文精简）
散文段落、列表项和引用行未硬换行（每个都是单行长文本；段落间用空行分隔，新的项目符号/引用行单独起一行）
Overview解释了“为什么”，而非仅“做什么”
Design捕捉了意图，而非实现细节
Plan项具体且可独立验证
Test项与Plan项对应
所有仓库特定的必填章节（如
```
## Provider impact
```
、
```
## Schema impact
```
）已包含，或规范确实未涉及该领域
人类/AI边界明确——没有“自行解决”的项
未重复现有Issue
依赖关系通过Issue编号引用

5. Publish

Create the issue using

mcp__github__issue_write

against the consumer repo:

Title format:

spec(<area>): <short description>

<area>

is drawn from the consumer repo's area-label taxonomy — read the

*-dev-process

sister skill (or the repo's CLAUDE.md if the sister skill defers) for the canonical list. Examples observed across consumer repos:

spec(stiglab): add session timeout

spec(provider): github provider — issue CRUD via MCP

spec(schema): add api/observe action type

Labels: Apply via the issue creation:

```
spec
```
— always, marks this as a spec issue
Type:
```
feat
```
,
```
fix
```
,
```
refactor
```
,
```
perf
```
Area (consumer-repo taxonomy)

Priority:

priority:critical

priority:high

priority:medium

priority:low

Status:
```
draft
```
(initial state)
Any consumer-repo cross-cutting labels (e.g.
```
provider-impact
```
,
```
schema-impact
```
,
```
i18n
```
) when the corresponding overlay section is non-empty

Sub-issues: If this is a child of a parent spec, link it using

mcp__github__sub_issue_write

After creating, report to the user:

Issue number and URL
Token count estimate (flag if over 2000)
Any open questions that need human decisions
Sub-issue links if the spec was split

使用

mcp__github__issue_write

在目标仓库创建Issue：

标题格式：

spec(<area>): <简短描述>

<area>

来自目标仓库的领域标签分类——请阅读

*-dev-process

姐妹技能（如果姐妹技能未指定，则参考仓库的CLAUDE.md）获取标准列表。各仓库中的示例：

spec(stiglab): add session timeout

spec(provider): github provider — issue CRUD via MCP

spec(schema): add api/observe action type

。

标签：在创建Issue时应用：

```
spec
```
—— 必选，标记此为规范Issue
类型：
```
feat
```
,
```
fix
```
,
```
refactor
```
,
```
perf
```
领域（仓库特定分类）

优先级：

priority:critical

priority:high

priority:medium

priority:low

状态：
```
draft
```
（初始状态）
任何仓库特定的跨领域标签（如
```
provider-impact
```
,
```
schema-impact
```
,
```
i18n
```
），当对应的附加章节非空时添加

子Issue：如果此为父规范的子Issue，请使用

mcp__github__sub_issue_write

链接。

创建后，向用户报告：

Issue编号和URL
预估token数（如果超过2000则标记）
任何需要人类决策的未解决问题
如果规范被拆分，提供子Issue链接

Status Lifecycle via Labels

通过标签实现状态生命周期

GitHub issue state (open/closed) combined with status labels:

open + draft  →  open + planned  →  open + in-progress  →  closed (complete)

draft: Spec created, open questions may remain. AI wrote it, human hasn't reviewed.
planned: Human reviewed, decisions made, ready for implementation. Remove
```
draft
```
, add
```
planned
```
.
in-progress: Someone/something is actively working (PR opened). Remove
```
planned
```
, add
```
in-progress
```
. Some consumer repos automate this transition via a
```
pr-spec-sync.yml
```
GitHub Actions workflow; others handle it manually — check the repo's
```
*-pr-lifecycle
```
sister skill.
closed: All plan items done, tests passing. PR merge with
```
Closes #N
```
closes it automatically.

Key rule:

draft → planned

is the human-AI alignment gate. A spec moves to

planned

only after a human reviews it and resolves open questions. The AI does not flip this label unprompted.

GitHub Issue状态（打开/关闭）结合状态标签：

open + draft  →  open + planned  →  open + in-progress  →  closed (complete)

draft：规范已创建，可能存在未解决问题。由AI撰写，尚未经过人工评审。
planned：人工评审完成，决策已确定，可开始实现。移除
```
draft
```
标签，添加
```
planned
```
标签。
in-progress：有人/系统正在积极处理（已打开PR）。移除
```
planned
```
标签，添加
```
in-progress
```
标签。部分仓库通过
```
pr-spec-sync.yml
```
GitHub Actions工作流自动完成此流转；其他仓库手动处理——请查看仓库的
```
*-pr-lifecycle
```
姐妹技能。
closed：所有计划项完成，测试通过。PR合并时标注
```
Closes #N
```
会自动关闭Issue。

关键规则：

draft → planned

是人机对齐的关卡。只有经过人工评审并解决未解决问题后，规范才能转为

planned

状态。AI不得未经提示自行切换此标签。

Spec Relationships via Sub-Issues

通过子Issue实现规范关系

Use GitHub sub-issues for parent/child decomposition:

Relationship	GitHub mechanism	When to use
Parent/Child	Sub-issues ( `mcp__github__sub_issue_write` )	Large feature decomposed into pieces
Depends On	Issue body reference ( `depends on #N` )	Spec blocked until another finishes
Related	Issue body reference ( `related: #N` )	Loosely connected specs

Decision rule: Remove the dependency — does the spec still make sense? If no → sub-issue (child). If yes but blocked → depends on.

Example decomposition (shape, not specific to any one repo):

spec(<area>): umbrella feature                ← parent issue
├── spec(<area>): concern A                   ← sub-issue
├── spec(<area>): concern B                   ← sub-issue
└── spec(<other-area>): UI surface for A+B    ← sub-issue

When a contract under a repo's architectural rule splits work across two subsystems (e.g. a back-end producer + a front-end consumer of an event), use the parent-plus-children shape: one parent spec captures the end-to-end slice, one child spec per subsystem captures its half. The contract lives in the parent's Plan; each child scopes to a single area label. Producer and consumer halves can land in separate PRs as long as both close before the parent does — but the parent's Plan should require a contract test that fails until both halves exist.

使用GitHub子Issue实现父/子拆分：

关系类型	GitHub机制	使用场景
父/子	子Issue（ `mcp__github__sub_issue_write` ）	大型功能拆分为多个部分
依赖于	Issue正文引用（ `depends on #N` ）	规范需等待其他规范完成后才能推进
相关	Issue正文引用（ `related: #N` ）	松散关联的规范

决策规则：移除依赖关系后，规范是否仍有意义？如果否 → 子Issue（子任务）。如果是但被阻塞 → 依赖于。

拆分示例（结构，不针对特定仓库）：

spec(<area>): 总览功能                ← 父Issue
├── spec(<area>): 关注点A                   ← 子Issue
├── spec(<area>): 关注点B                   ← 子Issue
└── spec(<other-area>): A+B的UI界面    ← 子Issue

当仓库架构规则要求将工作拆分到两个子系统（如事件的后端生产者 + 前端消费者）时，使用父+子结构：一个父规范涵盖端到端流程，每个子系统对应一个子规范。契约定义在父规范的Plan中；每个子规范仅涉及单个领域标签。生产者和消费者部分可分别提交PR，但两者都需在父Issue关闭前完成——父规范的Plan应要求一个契约测试，该测试在两部分都完成前会失败。

Guidance

指导原则

Small is better. A 500-token spec that captures intent clearly beats a 3000-token spec that tries to cover everything. Split into sub-issues early.
Discover first. Always search existing issues before creating. Duplicate specs create confusion.
Status labels reflect reality. Don't label
```
planned
```
if decisions are still open. Don't label
```
in-progress
```
until a PR is open.
One concern per issue. If a spec covers two independent changes, split into sub-issues with a shared parent.
Reference code, not concepts. Point to actual types, functions, files — not abstract ideas. Use concrete paths like
```
crates/<sub>/src/...
```
or
```
packages/<pkg>/src/...
```
rather than "the foo module."
Open questions are alignment points. These are where AI must stop and ask a human. Make them explicit, specific, and include the impact of each decision.
Comments are the decision record. When a human resolves an open question, they comment on the issue. The thread becomes the audit trail.
Use specs for alignment, not for everything. Regular bugs and small tasks don't need specs. Use specs when: multiple stakeholders need alignment, intent needs persistence, or the AI needs clear boundaries.

越小越好。一个500 token的清晰规范胜过一个3000 token试图覆盖所有内容的规范。尽早拆分为子Issue。
先探索。创建前务必搜索现有Issue。重复规范会造成混淆。
状态标签反映实际情况。如果决策仍未确定，不要标记为
```
planned
```
。PR未打开前，不要标记为
```
in-progress
```
。
一个Issue一个关注点。如果一个规范涵盖两个独立变更，拆分为子Issue并共享父Issue。
引用代码而非概念。指向实际的类型、函数、文件——而非抽象概念。使用具体路径如
```
crates/<sub>/src/...
```
或
```
packages/<pkg>/src/...
```
，而非“foo模块”。
未解决问题是对齐点。这些是AI必须停止并询问人类的地方。要明确、具体，并说明每个决策的影响。
评论是决策记录。当人类解决未解决问题时，会在Issue上评论。线程成为审计轨迹。
规范用于对齐，而非所有场景。常规Bug和小任务无需规范。在以下场景使用规范：多个利益相关方需要对齐、意图需要持久化、或AI需要明确边界。

Handoff to implementation

向实现阶段移交

Once a spec moves to

planned

Create a branch referencing the issue:
```
claude/spec-<N>-<slug>
```
(Claude-owned) or any name (human-owned).
Follow the SDD loop in the repo's
```
*-dev-process
```
sister skill.
Pre-push via the repo's
```
*-pre-push
```
sister skill (which typically includes a spec-link check plus the repo's typecheck / lint / test gates).
PR body must include
```
Closes #N
```
(slice complete) or
```
Part of #N
```
(scaffolding).
On PR open, the repo's
```
pr-spec-sync
```
workflow (if present) flips the issue to
```
in-progress
```
; on merge GitHub auto-closes
```
Closes #N
```
issues and the merger ticks Plan items on
```
Part of #N
```
parents manually. See
```
*-pr-lifecycle
```
.

一旦规范转为

planned

状态：

创建引用Issue的分支：
```
claude/spec-<N>-<slug>
```
（Claude维护）或任意名称（人类维护）。
遵循仓库
```
*-dev-process
```
姐妹技能中的SDD循环。
通过仓库的
```
*-pre-push
```
姐妹技能进行推送前检查（通常包括规范链接检查以及仓库的类型检查/ lint/测试关卡）。
PR正文必须包含
```
Closes #N
```
（完整实现）或
```
Part of #N
```
（框架搭建）。
PR打开后，仓库的
```
pr-spec-sync
```
工作流（如果存在）会将Issue转为
```
in-progress
```
状态；合并时GitHub会自动关闭标注
```
Closes #N
```
的Issue，合并者需手动勾选
```
Part of #N
```
父Issue的计划项。详情请查看
```
*-pr-lifecycle
```
。

Repo-agnostic by construction; consumer overlay is required

天生与仓库无关；需仓库定制规则

This skill is the methodology; it intentionally does not name a repo, an area taxonomy, or a set of cross-cutting labels. Every consumer repo overlays those via:

Its
```
CLAUDE.md
```
(repo-specific principles, target GitHub slug, always-spec surfaces).
Its
```
*-dev-process
```
sister skill (area-label taxonomy, spec-vs-
```
trivial
```
gate, SDD loop).
Its
```
*-pre-push
```
and
```
*-pr-lifecycle
```
sister skills (which gates run pre-push and which automation runs post-push).
Optionally an additional product spec doc (e.g.
```
docs/<product>-spec.md
```
, an architecture ADR set) that the repo's CLAUDE.md points at.

Treat reading those as part of step 1 (Discover). Don't draft a spec without having loaded the consumer repo's overlay context first — a spec that names the wrong area label, misses a required section, or proposes something the repo's seam / schema / provider rule forbids is a spec the human has to rewrite.

此技能是方法论；它故意不指定仓库、领域分类或跨领域标签集。每个使用此技能的仓库会通过以下内容添加这些定制规则：

其
```
CLAUDE.md
```
（仓库特定原则、目标GitHub标识、必须制定规范的场景）。
其
```
*-dev-process
```
姐妹技能（领域标签分类、规范与
```
trivial
```
的判定标准、SDD循环）。
其
```
*-pre-push
```
和
```
*-pr-lifecycle
```
姐妹技能（推送前检查关卡和推送后自动化流程）。
可选的额外产品规范文档（如
```
docs/<product>-spec.md
```
、架构ADR集），由仓库的CLAUDE.md指向。

请将阅读这些内容作为步骤1（Discover）的一部分。在未加载目标仓库的定制上下文前，不要起草规范——如果规范使用了错误的领域标签、遗漏了必填章节，或提出了违反仓库衔接/架构/供应商规则的内容，人类将不得不重写规范。

References

参考资料

Reference	When to read
references/spec-format.md	Always — section-by-section guide with worked examples
Repo's `CLAUDE.md`	Always — repo-specific principles + always-spec surfaces
Repo's `*-dev-process` sister skill	Always — area-label taxonomy + spec-vs- `trivial` gate
Repo's `*-pr-lifecycle` sister skill	When publishing — does the repo automate `pr-spec-sync` ?

参考资料	阅读时机
references/spec-format.md	必读——分章节指南及示例
仓库的 `CLAUDE.md`	必读——仓库特定原则 + 必须制定规范的场景
仓库的 `*-dev-process` 姐妹技能	必读——领域标签分类 + 规范与 `trivial` 的判定标准
仓库的 `*-pr-lifecycle` 姐妹技能	创建时阅读——仓库是否自动执行 `pr-spec-sync` ？

Templates

模板

Template	Purpose
templates/issue-spec-template.md	Universal issue body template — copy and fill

Consumer repos may ship an extended template alongside this one (e.g. with a

## Provider impact

## Schema impact

block pre-filled). Prefer the consumer-repo extended template when present.

模板	用途
templates/issue-spec-template.md	通用Issue正文模板——复制并填写内容

使用此技能的仓库可能会提供扩展模板（如预填充

## Provider impact

或

## Schema impact

块）。如果存在仓库定制的扩展模板，请优先使用。