capability-doc-generator

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Capability Doc Generator

能力文档生成器

Turn a business context description into a draft capability document: the business rules of one capability, written as
BR-XXX-0NN
statements in Given/When/Then form, with the business reason recorded for each.
将业务上下文描述转换为一份能力文档草稿:用
BR-XXX-0NN
编号、以 Given/When/Then 形式编写某一项能力的业务规则,并为每条规则记录业务原因。

Why 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 (
    UJ-00N
    ). Journeys reference capabilities, not the other way round — that is the
    journey
    skill's job. Point the user there (compose mode once the capabilities exist; discovery mode to find out which ones are needed).
  • Write to a
    policies/
    folder. Output always goes to
    capabilities/
    .
  • Claim the rules are implemented. See "Honest status" below.
  • Write the implementation code.
该 Skill 每次编写一份能力文档,描述预期行为。
即使在任务进行到一半时收到此类要求,也不要执行以下操作;应将其作为独立的后续工作另行提供:
  • 编写或更新 Journey 文档(
    UJ-00N
    )。Journey 引用 capability,而不是反过来;这是
    journey
    Skill 的职责。将用户引导至该 Skill(capability 已存在时使用 compose 模式;用于确定需要哪些 capability 时使用 discovery 模式)。
  • 写入
    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:
FieldValueReason
status:
planned
Nothing has been verified against code yet
implementation:
emptyThis field means "the rule is proven to be enforced here" — an unverified guess must never be recorded as proof
## Known gaps
Not yet implemented — verify against code after implementation.
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
## Related
as a reference bullet — never in
implementation:
. Keeping guesses out of the frontmatter is what makes the field trustworthy later.
该文档描述的是应该成立的内容,而不是当前实际成立的内容。针对真实代码验证规则属于另一项工作,并且需要不同的证据。因此:
字段值原因
status:
planned
尚未针对代码进行任何验证
implementation:
空此字段表示“已证明该规则在此处得到执行”;未经验证的猜测绝不能记录为证据
## Known gaps
Not yet implemented — verify against code after implementation.
缺口是指规则与代码之间的不一致;在没有经过验证的代码时,无可比较的对象
当用户指定现有文件作为参考或可能的变更目标时,将其作为参考条目记录在
## Related
下——绝不能放入
implementation:
。将猜测排除在 frontmatter 之外,才能确保该字段日后仍然可信。

Input needed

所需输入

Collect these before writing. Ask for whatever is missing rather than inventing it.
  1. Service — which service owns this capability (
    ciam
    ,
    task
    , ...). Determines the output folder and the
    BR-
    prefix.
  2. Capability name — becomes the
    id
    (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.
  3. 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.
  4. 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.
编写前应收集以下信息。对于缺失的内容应主动询问,而不是自行编造。
  1. Service——哪项服务负责此 capability(
    ciam
    、
    task
    等)。它决定输出文件夹和
    BR-
    前缀。
  2. Capability 名称——用作
    id
    (kebab-case)和 H1 标题。如果用户要求提供命名建议,应根据业务上下文给出 2–3 个选项供其选择。绝不能在不告知用户的情况下自行命名。
  3. 业务上下文——可以是自由格式:书面需求、会议记录或口头说明。无论采用何种形式,都应从中提取参与者、触发条件、规则和原因。
  4. 现有文件(可选)——参考代码或预期的变更目标。
如果业务上下文过于薄弱,以致规则只能靠猜测得出,应明确说明并询问缺失内容。充满虚构规则的文档比没有文档更糟糕。

Step 1 — Locate the repo and the capabilities folder

第 1 步——定位仓库和 capabilities 文件夹

Read
AGENTS.md
or
CLAUDE.md
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:
<service-root>/docs/business/capabilities/<id>.md
If 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.md
或
CLAUDE.md
,了解仓库名称和目录结构。单体仓库与多仓库的布局各不相同,因此应推导出路径,而不是直接假定:
<service-root>/docs/business/capabilities/<id>.md
如果该文件夹尚不存在,说明这是此服务的第一份能力文档——应明确告知用户,并在写入前与其确认路径。

Step 2 — Determine rule numbering

第 2 步——确定规则编号

Rule IDs use the pattern
BR-<SERVICE>-0NN
, where
<SERVICE>
is the service name in uppercase (
ciam
→
BR-CIAM
). If the service name is long or hyphenated, propose an abbreviation and confirm it.
Numbers 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..041
Each 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:
  1. Scan every
    .md
    in the capabilities folder and collect the rule IDs in use.
  2. Show the user the occupied blocks and what each appears to cover.
  3. Ask whether to continue an existing block or open a new one.
  4. Only then assign numbers.
Skip the scan only when the folder is empty — then propose starting at
001
and confirm.
规则 ID 使用
BR-<SERVICE>-0NN
格式,其中
<SERVICE>
是大写的服务名称(
ciam
→
BR-CIAM
)。如果服务名称较长或包含连字符,应提出一个缩写并与用户确认。
编号按语义分块,而不是依次顺序分配。真实服务可能如下所示:
BR-TASK-001..006   BR-TASK-010..017   BR-TASK-020..023   BR-TASK-030..041
每个代码块涵盖一个相关的行为领域。新 capability 属于哪个代码块是对含义的判断,而不是算术问题——因此不要猜测:
  1. 扫描 capabilities 文件夹中的每个
    .md
    文件,收集已使用的规则 ID。
  2. 向用户展示已占用的代码块,以及每个代码块似乎涵盖的内容。
  3. 询问用户是继续使用现有代码块,还是新建一个代码块。
  4. 只有在完成上述步骤后才分配编号。
仅当文件夹为空时可以跳过扫描——此时建议从
001
开始并与用户确认。

Step 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

TermMeaning
<Term><Business definition — not a field description>
TermMeaning
<Term><Business definition — not a field description>

Actors and triggers

Actors and triggers

TriggerActorEffect
<event or action><user / scheduler / inbound event><what happens>
TriggerActorEffect
<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

SituationExpected behaviourRule
<situation><behaviour>
BR-XXX-0NN
SituationExpected behaviourRule
<situation><behaviour>
BR-XXX-0NN

Examples

Examples

InputExpected outcome
<concrete values><concrete result>
InputExpected 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:
    <path>
    — <why it is relevant>
  • Sibling capabilities:
    <name>
  • Source document: <original requirement or design doc, if any>
undefined
  • Existing flow reference:
    <path>
    — <why it is relevant>
  • Sibling capabilities:
    <name>
  • Source document: <original requirement or design doc, if any>
undefined

Section 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
    status
    ,
    implementation:
    and Known gaps stay unfilled until the rules are verified against real code
写入文件后,应告知用户:
  • 文件写入了何处
  • 分配了哪些规则 ID,以及它们被归入哪个代码块
  • 哪些章节需要人工输入——通常是 Open questions,以及基于薄弱上下文推导出的内容
  • status
    、
    implementation:
    和
    Known gaps
    在规则针对真实代码完成验证前将保持未确认状态