菜单
Record an architecture/design decision as an ADR (Architecture Decision Record) in the target repository's docs/adr/. Use when the user wants to document a design decision, its alternatives and consequences, or says "record this decision" / "write an ADR".
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | create-adr |
| description | Record an architecture/design decision as an ADR (Architecture Decision Record) in the target repository's docs/adr/. Use when the user wants to document a design decision, its alternatives and consequences, or says "record this decision" / "write an ADR". |
| allowed-tools | Read Glob Grep Write Bash(git *) |
Record one architecture decision — the "why" that code and commit messages can't carry — as a numbered, immutable file in the target repository.
An ADR records a decision made, not a proposal under discussion. If the decision isn't settled yet, help settle it in conversation first; write the ADR after.
Locate the ADR home. Look for an existing convention in the target
repo: docs/adr/, docs/decisions/, adr/, or an existing NNNN-*.md
series anywhere under docs/. Follow whatever exists (numbering width,
template style). If none exists, create docs/adr/ and start at 0001.
Gather the decision. From the conversation (ask only for gaps): the decision itself, the context/forces that made it necessary, the alternatives considered, and why they lost. If the decision came out of work in this session, pull the concrete evidence (files, constraints) you already have instead of re-asking.
Draft the ADR — in English, as a repository artifact. Template (skip a section only when genuinely empty, and keep the heading with "None."):
# NNNN. <Decision title, imperative — "Use X for Y">
Date: YYYY-MM-DD
Status: Accepted
## Context
<the forces: requirements, constraints, problems that made a decision necessary>
## Decision
<what was decided, stated as fact>
## Alternatives considered
<each alternative and the concrete reason it was rejected>
## Consequences
<what becomes easier, what becomes harder, follow-ups now required>
Confirm, then write. Show the draft to the user; on approval write
NNNN-<kebab-slug-of-title>.md into the ADR home. If this ADR supersedes
an earlier one, also edit the old ADR's Status to
Superseded by NNNN — that edit is the one exception to ADR immutability.
Report the file path and suggest committing it with the related change
(docs: add ADR NNNN — <title>).
Status: Accepted
ADR for it; either help decide first or, if the user wants the open state
recorded, use Status: Proposed and say so.Generate a self-contained HTML manual-testing guide for an implemented change — environment setup, a visual test-flow diagram, step-by-step scenarios with expected results, and interactive pass/fail checkboxes with a Markdown results export. Use when the user wants to verify an implementation by hand, asks "how do I test this", or wants a verification document for a feature/branch/PR.
Generate a self-contained HTML onboarding tour of a repository — architecture diagram, directory map, key flow walkthroughs, and a recommended reading order — for new team members. Use when the user wants onboarding material, asks for a codebase overview/architecture tour, or wants to explain a repo to someone new.
Generate a self-contained HTML code-review guide for the current changes — big-picture overview, architecture diagram of affected modules, a file/class responsibility map, and an annotated change walkthrough — so a reviewer can grasp the whole implementation before diving into the diff. Use when the user wants review material for a branch/PR, asks to "explain the changes for review", or wants a visual summary of what was implemented where.
Investigate a reported bug to its root cause — reproduce, trace the code path, identify the defect with evidence, assess blast radius, and propose fix candidates without changing code. Use when the user reports or pastes a bug/defect/unexpected behavior and wants it diagnosed, or asks "why is X happening".
Capture a reusable, non-obvious project insight into the rules home where it will auto-inject in future sessions. Use when investigation or implementation surfaces knowledge worth persisting (a gotcha, a convention, the "why" behind a decision), or when the user asks to remember a project learning.
Implement a small, well-scoped feature or fix end-to-end from spec to PR — reuse or create a feature branch, implement test-first, run static checks, get user verification, commit, then open a PR to main.