adr
Trigger: ADR, architecture decision, decision record, por qué elegimos X, documentar decisión. Teach agents how to find, read, create, and update Architecture Decision Records across all workflows.
- License 许可
- MIT
- 最近更新
- 2026-08-26
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- adr
- license
- MIT
- metadata
- { "author": "gentleman-programming", "version": "1.0" }
- description
- Trigger: ADR, architecture decision, decision record, por qué elegimos X, documentar decisión. Teach agents how to find, read, create, and update Architecture Decision Records across all workflows.
02 资源文件 4
- 资产文件assets/template.md1.3 KB
- 其他hooks/post-commit1.6 KB
- 其他hooks/pre-commit1.3 KB
- 脚本scripts/update-index.sh3.3 KB
03 SKILL.md 正文
ADR - Architecture Decision Records
Activation Contract
Use this skill when:
- Creating a new architecture decision record
- Consulting existing ADRs before making a decision
- Updating an ADR's status (accepted, deprecated, superseded)
- Linking ADRs to specs, designs, or implementation tasks
Do not use for:
- Trivial decisions (ESLint vs Prettier, tab size)
- Implementation details that don't affect architecture
- Personal preferences without team impact
Hard Rules
- ADRs live in
docs/adr/at the project root - Every ADR must be listed in
docs/adr/index.md - When creating an ADR, you MUST update the index
- Use the template from
assets/template.mdexactly — do not deviate - ADRs are numbered sequentially:
001-short-name.md,002-another-decision.md - When superseding an ADR, you MUST add a
Superseded bylink in both the old and new ADR - ADRs are the canonical S2 (decisions) tier of the project knowledge base — see
ck:context-architecture→ The Second Axis: Knowledge Stability. S2 is always file-canonical because ADRs get reviewed in pull requests. Other artifacts (Engram topic_keys,context/, specs) link todocs/adr/and MUST NOT copy ADR content.
Decision Gates
| Situation | Action |
|---|---|
| New architectural decision with real tradeoffs | Create ADR |
| Decision affects multiple workflows or teams | Create ADR |
| Trivial tooling or style choice | Skip ADR |
| Decision already documented in an existing ADR | Reference it, don't duplicate |
| Previous ADR is now wrong or outdated | Create new ADR, mark old as superseded |
Execution Steps
Finding Existing ADRs
- Read
docs/adr/index.mdto see all ADRs with their status and keywords - Identify ADRs relevant to your current task by:
- Scanning titles for domain match
- Checking keywords column for specific terms
- Looking at status (prefer
Accepted, avoidSupersededunless tracing history)
- Read only the relevant ADR files — do not load all ADRs
Creating a New ADR
- Determine the next ADR number by reading
docs/adr/index.md - Copy
assets/template.mdtodocs/adr/{NNN}-{short-name}.md - Fill in all sections:
- Title: Number + short descriptive name
- Status: Start with
Proposed - Context: What problem are we solving? What options did we consider?
- Decision: What did we choose and WHY? (the why is critical)
- Consequences: What changes? What becomes easier? What becomes harder?
- Superseded by: Leave empty unless this replaces another ADR
- Update
docs/adr/index.mdby adding a row to the table - Run
bash {skill-dir}/scripts/update-index.shto verify the index is complete
Updating an ADR
- Status changes: Update the
Statusfield (Proposed → Accepted, Accepted → Deprecated, etc.) - Superseding: When creating ADR-NNN that replaces ADR-MMM:
- In ADR-MMM: change Status to
Superseded, addSuperseded by: [ADR-NNN](./NNN-name.md) - In ADR-NNN: add
Supersedes: [ADR-MMM](./MMM-name.md)in the header
- In ADR-MMM: change Status to
- Content updates: If the decision rationale changes, update the ADR and add a revision date
Linking ADRs to Work
- In specs/kits: Reference ADRs that constrain the design:
See [ADR-002](../docs/adr/002-hexagonal.md) - In designs: Link ADRs that informed the visual/UX decisions
- In implementation tasks: Reference ADRs that explain why the code is structured a certain way
- In code comments: For critical architectural choices, add a comment:
// See docs/adr/001-auth-jwt.md
Regenerating the Index
If the index is out of sync or you want to verify it:
bash {skill-dir}/scripts/update-index.sh
This script:
- Scans
docs/adr/*.md(excludingindex.md) - Extracts title, status, and keywords from each ADR
- Regenerates
docs/adr/index.mdwith a complete table - Reports any ADRs that are missing required fields
Output Contract
When creating an ADR, return:
- The path to the new ADR file
- Confirmation that the index was updated
- Any warnings about missing fields or formatting issues
When consulting ADRs, return:
- Which ADRs were consulted
- Key decisions that affect the current task
- Any conflicts or outdated decisions found
References
assets/template.md— The ADR template (use exactly)scripts/update-index.sh— Script to regenerate the index from ADR files
04 同仓库更多 Skills
zustand-5
Zustand 5 state management patterns. Trigger: When managing React state with Zustand.
zod-4
Zod 4 schema validation patterns. Trigger: When using Zod for validation - breaking changes from v3.
x-bookmark-quote-posts
Workflow para revisar bookmarks de X/Twitter y convertirlos en drafts de quote posts. Accede a la sección de bookmarks vía browser headless, extrae posts recientes, y genera drafts con voz personal del usuario. No publica ni muta X — solo genera contenido para revisión. Trigger: X bookmarks, Twitter bookmarks, quote posts, bookmark automation, crear quote posts, revisar bookmarks, growth content X.
writing-skills
Use when creating new skills, editing existing skills, or verifying skills work before deployment
writing-plans
Use when you have a spec or requirements for a multi-step task, before touching code
work-unit-commits
Plan commits as reviewable work units. Trigger: implementation, commit splitting, chained PRs, or keeping tests and docs with code.