capability-doc-generator
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseCapability Doc Generator
能力文档生成器
Turn a business context description into a draft capability document: the business
rules of one capability, written as statements in Given/When/Then form, with
the business reason recorded for each.
BR-XXX-0NN将业务上下文描述转换为一份能力文档草稿:用 编号、以 Given/When/Then 形式编写某一项能力的业务规则,并为每条规则记录业务原因。
BR-XXX-0NNWhy this exists
存在原因
Rules can be reverse-engineered from code. The reason behind a rule cannot. Once a
feature ships, the "why" lives only in someone's memory and disappears when they leave the
team. This skill captures that reasoning while it is still fresh — before implementation,
when the business intent is being discussed.
The Why line under each rule is the highest-value part of the output. Never skip it,
never fill it with a restatement of the rule.
规则可以从代码中反向推导,但规则背后的原因无法推导。功能上线后,“为什么”只存在于某个人的记忆中,待其离开团队后便会随之消失。该 Skill 会在实施之前、讨论业务意图期间,趁着相关思路仍然清晰将其记录下来。
每条规则下的 Why 行是输出中价值最高的部分。绝不能省略,也绝不能用规则的复述来填充。
Scope boundaries
范围边界
This skill writes one capability document at a time, describing intended behaviour.
Do NOT do these, even if asked mid-task — offer them as separate follow-up work instead:
- Write or update a journey document (). Journeys reference capabilities, not the other way round — that is the
UJ-00Nskill's job. Point the user there (compose mode once the capabilities exist; discovery mode to find out which ones are needed).journey - Write to a folder. Output always goes to
policies/.capabilities/ - Claim the rules are implemented. See "Honest status" below.
- Write the implementation code.
该 Skill 每次编写一份能力文档,描述预期行为。
即使在任务进行到一半时收到此类要求,也不要执行以下操作;应将其作为独立的后续工作另行提供:
- 编写或更新 Journey 文档()。Journey 引用 capability,而不是反过来;这是
UJ-00NSkill 的职责。将用户引导至该 Skill(capability 已存在时使用 compose 模式;用于确定需要哪些 capability 时使用 discovery 模式)。journey - 写入 文件夹。输出始终应写入
policies/。capabilities/ - 声称规则已经实现。请参阅下文“真实状态”。
- 编写实现代码。
Honest status
真实状态
The document describes what should be true, not what is true. Verifying rules against
real code is separate work with different evidence requirements. So:
| Field | Value | Reason |
|---|---|---|
| | Nothing has been verified against code yet |
| empty | This field means "the rule is proven to be enforced here" — an unverified guess must never be recorded as proof |
| | A gap is a mismatch between rules and code; with no verified code there is nothing to compare |
When the user names existing files as reference or as the likely target of change, record
them under as a reference bullet — never in . Keeping guesses
out of the frontmatter is what makes the field trustworthy later.
## Relatedimplementation:该文档描述的是应该成立的内容,而不是当前实际成立的内容。针对真实代码验证规则属于另一项工作,并且需要不同的证据。因此:
| 字段 | 值 | 原因 |
|---|---|---|
| | 尚未针对代码进行任何验证 |
| 空 | 此字段表示“已证明该规则在此处得到执行”;未经验证的猜测绝不能记录为证据 |
| | 缺口是指规则与代码之间的不一致;在没有经过验证的代码时,无可比较的对象 |
当用户指定现有文件作为参考或可能的变更目标时,将其作为参考条目记录在 下——绝不能放入 。将猜测排除在 frontmatter 之外,才能确保该字段日后仍然可信。
## Relatedimplementation:Input needed
所需输入
Collect these before writing. Ask for whatever is missing rather than inventing it.
- Service — which service owns this capability (,
ciam, ...). Determines the output folder and thetaskprefix.BR- - Capability name — becomes the (kebab-case) and the H1 title. If the user asks for a naming suggestion, offer 2–3 options derived from the business context and let them choose. Never silently invent one.
id - Business context — free-form: a written requirement, meeting notes, or a verbal explanation. Whatever form it takes, extract actors, triggers, rules, and reasons from it.
- Existing files (optional) — reference code or the expected target of change.
If the business context is thin enough that the rules would be guesswork, say so and ask
for the missing part. A document full of invented rules is worse than no document.
编写前应收集以下信息。对于缺失的内容应主动询问,而不是自行编造。
- Service——哪项服务负责此 capability(、
ciam等)。它决定输出文件夹和task前缀。BR- - Capability 名称——用作 (kebab-case)和 H1 标题。如果用户要求提供命名建议,应根据业务上下文给出 2–3 个选项供其选择。绝不能在不告知用户的情况下自行命名。
id - 业务上下文——可以是自由格式:书面需求、会议记录或口头说明。无论采用何种形式,都应从中提取参与者、触发条件、规则和原因。
- 现有文件(可选)——参考代码或预期的变更目标。
如果业务上下文过于薄弱,以致规则只能靠猜测得出,应明确说明并询问缺失内容。充满虚构规则的文档比没有文档更糟糕。
Step 1 — Locate the repo and the capabilities folder
第 1 步——定位仓库和 capabilities 文件夹
Read or at the repo root to learn the repo name and layout. The
layout differs between mono-repo and poly-repo, so derive the path rather than assuming:
AGENTS.mdCLAUDE.md<service-root>/docs/business/capabilities/<id>.mdIf the folder does not exist yet, this is the service's first capability doc — say so, and
confirm the path with the user before writing.
读取仓库根目录下的 或 ,了解仓库名称和目录结构。单体仓库与多仓库的布局各不相同,因此应推导出路径,而不是直接假定:
AGENTS.mdCLAUDE.md<service-root>/docs/business/capabilities/<id>.md如果该文件夹尚不存在,说明这是此服务的第一份能力文档——应明确告知用户,并在写入前与其确认路径。
Step 2 — Determine rule numbering
第 2 步——确定规则编号
Rule IDs use the pattern , where is the service name in
uppercase ( → ). If the service name is long or hyphenated, propose an
abbreviation and confirm it.
BR-<SERVICE>-0NN<SERVICE>ciamBR-CIAMNumbers are grouped in semantic blocks, not assigned sequentially. A real service looks
like this:
BR-TASK-001..006 BR-TASK-010..017 BR-TASK-020..023 BR-TASK-030..041Each block covers a related area of behaviour. Which block a new capability belongs to is
a judgement about meaning, not arithmetic — so do not guess:
- Scan every in the capabilities folder and collect the rule IDs in use.
.md - Show the user the occupied blocks and what each appears to cover.
- Ask whether to continue an existing block or open a new one.
- Only then assign numbers.
Skip the scan only when the folder is empty — then propose starting at and confirm.
001规则 ID 使用 格式,其中 是大写的服务名称( → )。如果服务名称较长或包含连字符,应提出一个缩写并与用户确认。
BR-<SERVICE>-0NN<SERVICE>ciamBR-CIAM编号按语义分块,而不是依次顺序分配。真实服务可能如下所示:
BR-TASK-001..006 BR-TASK-010..017 BR-TASK-020..023 BR-TASK-030..041每个代码块涵盖一个相关的行为领域。新 capability 属于哪个代码块是对含义的判断,而不是算术问题——因此不要猜测:
- 扫描 capabilities 文件夹中的每个 文件,收集已使用的规则 ID。
.md - 向用户展示已占用的代码块,以及每个代码块似乎涵盖的内容。
- 询问用户是继续使用现有代码块,还是新建一个代码块。
- 只有在完成上述步骤后才分配编号。
仅当文件夹为空时可以跳过扫描——此时建议从 开始并与用户确认。
001Step 3 — Write the document
第 3 步——编写文档
Use this structure exactly. Keep every heading, in this order, even when a section is short.
markdown
---
id: <kebab-case-capability-id>
service: <service>
status: planned
rules: BR-XXX-0NN..BR-XXX-0NN
updated: YYYY-MM-DD
implementation:
---严格使用以下结构。即使某个章节内容较短,也必须保留每个标题及其顺序。
markdown
---
id: <kebab-case-capability-id>
service: <service>
status: planned
rules: BR-XXX-0NN..BR-XXX-0NN
updated: YYYY-MM-DD
implementation:
---<Capability Name>
<Capability Name>
Purpose
Purpose
Two or three sentences: what business outcome this capability delivers and for whom.
Two or three sentences: what business outcome this capability delivers and for whom.
Ubiquitous language
Ubiquitous language
| Term | Meaning |
|---|---|
| <Term> | <Business definition — not a field description> |
| Term | Meaning |
|---|---|
| <Term> | <Business definition — not a field description> |
Actors and triggers
Actors and triggers
| Trigger | Actor | Effect |
|---|---|---|
| <event or action> | <user / scheduler / inbound event> | <what happens> |
| Trigger | Actor | Effect |
|---|---|---|
| <event or action> | <user / scheduler / inbound event> | <what happens> |
Rules
Rules
BR-XXX-0NN — <Statement of the rule>
BR-XXX-0NN — <Statement of the rule>
Given <precondition>
When <trigger>
Then <required outcome>
Why: <the business reason — the part not recoverable from the code>
Given <precondition>
When <trigger>
Then <required outcome>
Why: <the business reason — the part not recoverable from the code>
Edge cases
Edge cases
| Situation | Expected behaviour | Rule |
|---|---|---|
| <situation> | <behaviour> | |
| Situation | Expected behaviour | Rule |
|---|---|---|
| <situation> | <behaviour> | |
Examples
Examples
| Input | Expected outcome |
|---|---|
| <concrete values> | <concrete result> |
| Input | Expected outcome |
|---|---|
| <concrete values> | <concrete result> |
Known gaps
Known gaps
Not yet implemented — verify against code after implementation.
Not yet implemented — verify against code after implementation.
Open questions
Open questions
<Unresolved product decisions, each with who needs to decide. "None." if there are none.>
<Unresolved product decisions, each with who needs to decide. "None." if there are none.>
Related
Related
- Existing flow reference: — <why it is relevant>
<path> - Sibling capabilities:
<name> - Source document: <original requirement or design doc, if any>
undefined- Existing flow reference: — <why it is relevant>
<path> - Sibling capabilities:
<name> - Source document: <original requirement or design doc, if any>
undefinedSection notes
各部分说明
Purpose — state the business outcome, not the mechanism. "Decides who may read the
member directory" is useful; "Handles the GET /members endpoint" is not.
Ubiquitous language — only terms this capability introduces. Terms already defined in
the service overview or the global glossary belong there, so link instead of redefining.
When unsure whether a term is already defined elsewhere, leave it out and note it as an
open question — a duplicated definition that later drifts out of sync is worse than a
missing one.
Rules — one rule per distinct decision. If a rule's Then clause contains "and also",
it is probably two rules. Write Why as the business consequence of not having the rule,
which is what makes it impossible to recover from reading code later.
Edge cases — the situations someone would get wrong when implementing. Every row cites
a rule; if a row has no rule to cite, either a rule is missing or the row is noise.
Examples — concrete values, not placeholders. These become test cases.
Open questions — genuinely useful here. Gaps in the business context surface as
questions rather than as invented rules. Name who decides.
Purpose——说明业务结果,而不是实现机制。“决定哪些人可以读取 member directory”很有用;“处理 GET /members endpoint”则没有。
Ubiquitous language——只收录此 capability 引入的术语。已经在服务概览或全局术语表中定义的术语应放在那里,并改为链接,而不是重新定义。如果不确定某个术语是否已在其他地方定义,应将其省略,并作为开放问题记录——重复定义日后可能逐渐失去同步,这比暂时缺少定义更糟糕。
Rules——每个独立决策对应一条规则。如果规则的 Then 子句中出现“and also”,它很可能应当拆成两条规则。Why 应说明缺少该规则会造成什么业务后果,因为这正是日后仅通过阅读代码无法恢复的信息。
Edge cases——记录实现时容易出错的情况。每一行都必须引用一条规则;如果某行没有可引用的规则,要么缺少了一条规则,要么该行属于无关内容。
Examples——使用具体值,而不是占位符。这些示例将成为测试用例。
Open questions——此处应包含真正有价值的问题。业务上下文中的缺口应表现为问题,而不是被写成虚构规则。必须注明由谁作决定。
Step 4 — Report back
第 4 步——回报结果
After writing the file, tell the user:
- Where it was written
- Which rule IDs were assigned, and which block they went into
- Which sections need human input — typically Open questions, and anything derived from thin context
- That ,
statusand Known gaps stay unfilled until the rules are verified against real codeimplementation:
写入文件后,应告知用户:
- 文件写入了何处
- 分配了哪些规则 ID,以及它们被归入哪个代码块
- 哪些章节需要人工输入——通常是 Open questions,以及基于薄弱上下文推导出的内容
- 、
status和implementation:在规则针对真实代码完成验证前将保持未确认状态Known gaps