地址

人工智能 社区

技能解读

当前原文的自动摘译,尚未人工审校。

为什么存在这个技能

安东需要一栋耐用的住宅来进行建筑决策,以便:cluster-intake-gatekeeper有地方可以交出其添加/推迟/拒绝判决(而不是停留在“ADR 就绪”)。未来的 Codex 会话可以通过 SessionStart 挂钩自动发现先前的决策(.Codex/hooks/inject_adr_index.py),无需操作员输入。cluster-intake第2步可以查询过去Reverted按类别做出决定,而不是 grep 单个共享文件。

硬性规定

ADR 是一成不变的。一旦 ADRstatus:是Accepted(或Reverted/Rejected/Deferred),身体永远不会改变。对现有 ADR 唯一允许的编辑是翻转status:线路到Superseded-by NNNN。任何其他变更都必须经过supersede。数字永远不会重复使用。下一个数字总是max(existing) + 1,用零填充为四位数字,无论之前的数字是否被取代。

工作流程——新

触发方式:用户说“创建 ADR”/“记录此决定”//adr new "<title>" cluster-intake-gatekeeper移交添加/推迟/拒绝裁决(裁决对象替代交互式访谈 - 请参阅下面的“从入学移交”)

步骤

分配下一个数字。Glob('context/adrs/0[0-9][0-9][0-9]-*.md')。种类。下一个数字是max + 1,补零至 4 位数字。切勿重复使用号码。生成段头。小写标题,采用横写,去掉冠词和介词,取前 4-6 个有意义的单词。示例:“针对 CNI 采用 Cilium 而不是 Calico”→adopt-cilium-over-calico-for-cni→ 文件0018-adopt-cilium-over-calico-for-cni.md。

从入口处移交

当cluster-intake-gatekeeper在评估结束时调用该技能,它直接传递判决对象。将判决映射到 ADR 字段,无需重新访谈:Gatekeeper 判决·ADRstatus:· 备注添加(具体需要)·Accepted·intent: concrete-need。决策部分命名了交接技能(add-flux-app/flux-app-author)。后果部分包括 Renovate-PR 税项。

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
人工智能
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@wcygan · 未声明许可证
上下文用量评级
低消耗
接入复杂程度
即装即用
是否需要外部接口密钥
不需要
兼容的系统
未声明(默认跨平台)
运行环境要求
未检出明确要求
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
网络行为
仅限本地
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md

# ADR

Anton-local skill for the architectural decision record lifecycle. Owns three workflows: **new**, **list**, **supersede**. ADRs live at `context/adrs/NNNN-kebab-slug.md` and are immutable — once accepted, the body never changes. Supersession is the only way to revise a decision.

## Why this skill exists

Anton needs **one durable home** for architectural decisions so that:
- `cluster-intake-gatekeeper` has somewhere to hand off its ADD/DEFER/REJECT verdicts (instead of stopping at "ADR-ready").
- Future Codex sessions can discover prior decisions automatically via the SessionStart hook (`.Codex/hooks/inject_adr_index.py`) without the operator typing them in.
- `cluster-intake` Step 2 can query past `Reverted` decisions by category instead of grepping a single shared file.
- The operator (and future-Will) can recover *why* the cluster looks the way it does without mining `git log`.

The skill is anton-local and has **no runtime dependency** on `~/.Codex/skills/context-repo-adr` — the format is intentionally compatible with the global context-repo conventions, but invoking this skill never delegates to that one.

## Hard rules

- **ADRs are immutable.** Once an ADR's `status:` is `Accepted` (or `Reverted` / `Rejected` / `Deferred`), the body never changes. The *only* edit allowed on an existing ADR is flipping the `status:` line to `Superseded-by NNNN`. Any other change must go through `supersede`.
- **Numbers are never reused.** The next number is always `max(existing) + 1`, zero-padded to four digits, regardless of whether earlier numbers were superseded.
- **`Status: Reverted`** is anton-specific. Use it for any decision that was once live and is now removed. Standard MADR has no equivalent.

References:
- Field reference and immutability rule → [conventions](references/conventions.md)
- Canonical template for new ADRs → [template](references/template.md)

## Workflow — `new`

Triggered by:
- The user says "create an ADR" / "record this decision" / `/adr new "<title>"`
- `cluster-intake-gatekeeper` hands off an ADD / DEFER / REJECT verdict (the verdict object substitutes for the interactive interview — see "Handoff from intake" below)

### Steps

1. **Allocate the next number.** `Glob('context/adrs/0[0-9][0-9][0-9]-*.md')`. Sort. The next number is `max + 1`, zero-padded to 4 digits. Never reuse a number.

2. **Generate the slug.** Lowercase the title, kebab-case it, drop articles and prepositions, take the first 4–6 meaningful words. Example: "Adopt Cilium over Calico for CNI" → `adopt-cilium-over-calico-for-cni` → file `0018-adopt-cilium-over-calico-for-cni.md`.

3. **Interview the user** (skip this when invoked from intake — see Handoff from intake). Ask only the questions whose answers aren't already known:
   - Title (one short sentence)
   - One-sentence summary (the blockquote after the H1)
   - `status` — usually `Accepted` for forward-looking decisions; `Deferred` / `Rejected` / `Reverted` if known
   - `affects` — pick the broadest applicable category from: `storage`, `observability`, `databases`, `registries`, `demos`, `networking`, `security`, `compute`, `all`, or a new category if none fit
   - `intent` — `concrete-need` / `learning` / `unknown`
   - `supersedes` — list of NNNNs being superseded by this one (usually empty)
   - **Context** (1–3 paragraphs — what situation prompts this decision, what forces are in play)
   - **Decision** (active voice, one or two sentences — "We will adopt X" / "We will not")
   - **Alternatives considered** (do-nothing + 1–2 alternatives, with a one-line "why rejected" each)
   - **Consequences** — accepted costs, lessons (if `Reverted`), follow-ups

4. **Write the ADR file** at `context/adrs/NNNN-slug.md` using the shape from [template](references/template.md). Frontmatter is mandatory; missing frontmatter fields default to the template's defaults.

5. **If `supersedes:` is non-empty**, also flip the `status:` line of each superseded ADR to `Superseded-by NNNN`. This is the *only* allowed in-place edit on an existing ADR. Use `Edit` with a precise old/new string for the status line only — never touch the body.

6. **Confirm to the user** with the file path and the new ADR number.

### Handoff from intake

When `cluster-intake-gatekeeper` invokes this skill at the end of its evaluation, it passes the verdict object directly. Map the verdict to ADR fields without re-interviewing:

| Gatekeeper verdict | ADR `status:` | Notes |
|---|---|---|
| Add (concrete need) | `Accepted` | `intent: concrete-need`. Decision section names the hand-off skill (`add-flux-app` / `flux-app-author`). Consequences section includes the Renovate-PR tax line. |
| Add (learning) | `Accepted` | `intent: learning`. Consequences section *must* include the timebox, exit plan, and review date — these are load-bearing under the contained-learning rubric. The frontmatter should add a `review-by:` field with the review date. |
| Defer | `Deferred` | Body holds the exact measurable unblock conditions (what would have to be true to convert to Accepted). |
| Reject | `Rejected` | Body holds the failed gate (1–7) or known-bad pattern, and — if appropriate — whether reframing as a learning intake would change the answer. |

After writing the ADR, return to the gatekeeper with the ADR number so it can include it in its memory append.

## Workflow — `list`

Triggered by:
- `/adr list` or `/adr list --status Reverted` or `/adr list --affects databases`
- `cluster-intake` Step 2 (the removal-detection lookup) — internally invokes this with `--status Reverted --affects <candidate-category>` to find prior reverts

### Steps

1. `Glob('context/adrs/0[0-9][0-9][0-9]-*.md')`.
2. For each file, read the frontmatter and extract `status`, `date`, `affects`, `intent`, and the H1 title.
3. Apply filters:
   - `--status <X>` → keep only ADRs whose `status:` matches `X` (case-insensitive)
   - `--affects <X>` → keep only ADRs whose `affects:` contains `X`
   - With no filter, return all
4. Format as a markdown table sorted by NNNN (columns: #, Title, Status, Date, Affects, Intent).
5. If used as the data source for `cluster-intake` Step 2: also read the matching ADRs' "Re-adoption guidance" section so the intake can surface the conditions under which a re-attempt would be valid.

## Workflow — `supersede`

Triggered by:
- `/adr supersede <NNNN> "<reason>"` — the user wants to revise an existing decision

### Steps

1. **Verify the target exists.** `Read` `context/adrs/NNNN-*.md`. If missing, abort with a clear error.
2. **Verify the target's current status.** If it is already `Superseded-by NNNN`, abort — supersession chains exist (NNNN can be superseded by MMMM which is superseded by PPPP), so the user must supersede the *latest* in the chain.
3. **Author the replacement** by invoking the `new` workflow with `supersedes: [<NNNN>]` pre-populated. Walk the interview as normal.
4. **Flip the old ADR's status line** — and *only* the status line — from `Accepted` (or whatever it was) to `Superseded-by <new NNNN>`. Use `Edit` with the precise old/new strings. Do not touch the body, the date, or any other field.
5. **Confirm to the user** with both ADR numbers (old → new) and the file paths.

## What this skill does NOT do

- Does not write Flux manifests — that is `add-flux-app`.
- Does not run cluster intake — that is `cluster-intake` (which hands off here).
- Does not edit ADR bodies after the fact. Ever. Use `supersede`.
- Does not auto-detect when a decision should be superseded. Manual via `/adr supersede`.
- Does not push, commit, or tag — the user owns git operations.
- Does not delete ADRs. ADRs are append-only forever, even superseded ones.

## Related skills and agents

- `cluster-intake` / `cluster-intake-gatekeeper` — the dominant authoring path. Hand off here on every verdict.
- `add-flux-app` / `flux-app-author` — invoked *after* an `Accepted` ADR that involves new manifests.
- `~/.Codex/skills/context-repo-adr` (user-level) — format-compatible but not invoked at runtime. If the user adopts the full context-repo convention later, the existing ADRs will Just Work.

## Anti-patterns

- **Editing an ADR body to reflect a changed decision.** That's what `supersede` is for. Editing in place destroys the historical record.
- **Re-using a number after a delete.** ADRs are never deleted, so this shouldn't come up — but if it does, allocate the next number, never the gap.
- **Authoring an ADR before the decision is actually made.** ADRs document decisions that happened, not aspirations. If the user is still considering, they're not ready for an ADR.
- **Verbose ADRs.** One screen of body is the target. If the decision genuinely needs more context, link to a doc — don't inline it.

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。