做什么
为代理编码工作流程创建和维护优化的架构决策记录
技能库 智客分类:Agent 工作流 adr-skill
为代理编码工作流程创建和维护优化的架构决策记录(ADR). 当您需要提议、写入、更新、接受/拒绝、贬值或替换一个 ADR 时使用; 拖曳一个 dr 文件夹和索引; 在执行修改前查阅现有的 ADR ; 或执行 ADR 常规 。 这种技能使用 Socratic 质询在起草前捕捉意图,并对照代理准备清单验证输出.
官方网址:skills.sh
先看中文介绍;官方 description 原文单独保留,不改写 SKILL.md。
为代理编码工作流程创建和维护优化的架构决策记录
简单 vs MADR 风格模板
按 Agent Skills 渐进披露:启动时只加载 name 与 description(约 100 token);任务匹配后才读入整份 SKILL.md 正文;scripts/、references/、assets/ 仅在需要时再读。 本文件正文结构:ADR Skill、Philosophy、When to Write an ADR、Proactive ADR Triggers (For Agents)、Creating an ADR: Four-Phase Workflow、Phase 0: Scan the Codebase。 其中含规范建议的小节:分步指令。
文件分析:除 SKILL.md 外,正文引用了 assets/templates/adr-simple.md、assets/templates/adr-madr.md、references/template-variants.md、scripts/new_adr.js、assets/templates/、references/review-checklist.md,属于带资源的技能包,这些文件按需再读。
Create and maintain Architecture Decision Records (ADRs) optimized for agentic coding workflows. Use when you need to propose, write, update, accept/reject, deprecate, or supersede an ADR; bootstrap an adr folder and index; consult existing ADRs before implementing changes; or enforce ADR conventions. This skill uses Socratic questioning to capture intent before drafting, and validates output against an agent-readiness checklist.
ADR SkillPhilosophyWhen to Write an ADRProactive ADR Triggers (For Agents)Creating an ADR: Four-Phase WorkflowPhase 0: Scan the CodebasePhase 1: Capture Intent (Socratic)Phase 2: Draft the ADRPhase 3: Review Against ChecklistConsulting ADRs (Read Workflow)When to Consult ADRsHow to Consult ADRs
来源分类:skills.sh agent-skill
nameadr-skilldescriptionassets/templates/adr-simple.mdassets/templates/adr-madr.mdreferences/template-variants.mdscripts/new_adr.jsassets/templates/references/review-checklist.mdscripts/set_adr_status.jsscripts/bootstrap_adr.js以下路径提取自原文;文件是否齐全请以来源仓库中的完整目录为准。
具体调用语法与可用工具以目标 Agent 客户端为准。 查看调用机制说明 ↗
先选择目标 Agent 和安装范围,保留技能包的附属文件,安装后检查客户端能否发现该技能。
该技能引用了附属文件,请从来源获取完整目录;仅复制 SKILL.md 可能缺少依赖。
复制安装指令给支持 Agent Skills 的代理,确认其中的目标目录与客户端匹配。
把 Agent Skill「adr-skill」安装到我的项目:SKILL.md 原文与官方 description 见 https://zicq.com/zh/skills/skl-9fee466509ba8e0e-%E9%98%BF%E5%BE%B7%E5%B0%94%E6%8A%80%E8%83%BD.html 请存为 .cursor/skills/adr-skill/SKILL.md 或 .claude/skills/adr-skill/SKILL.md,frontmatter 的 name 与 description 保持原样,不要改写。 该技能还带 scripts/、references/、assets/ 等文件,请从 https://github.com/vercel/ai 取完整目录,不要只建一个 SKILL.md。
需要 Node.js 与 npx。先查看仓库技能列表,确认实际名称。
npx skills add 'https://github.com/vercel/ai' --list
npx skills add 'https://github.com/vercel/ai' --skill 'adr-skill'
CLI 会交互选择目标 Agent,默认安装到项目;用户级安装使用 -g。先通过查看命令核对仓库内容,再用 npx skills list 检查已安装技能。
ADRs created with this skill are executable specifications for coding agents. A human approves the decision; an agent implements it. The ADR must contain everything the agent needs to write correct code without asking follow-up questions.
This means:
Write an ADR when a decision:
Do NOT write an ADR for:
When in doubt: if a future agent working in this codebase would benefit from knowing why this choice was made, write the ADR.
If you are an agent coding in a repo and you encounter any of these situations, stop and propose an ADR before continuing:
How to propose: Tell the human what decision you've hit, why it matters, and ask if they want to capture it as an ADR. If yes, run the full four-phase workflow. If no, note the decision in a code comment and move on.
Every ADR goes through four phases. Do not skip phases.
Before asking any questions, gather context from the repo:
Find existing ADRs. Check contributing/decisions/, docs/decisions/, adr/, docs/adr/, decisions/ for existing records. Read them. Note:
Check the tech stack. Read package.json, go.mod, requirements.txt, Cargo.toml, or equivalent. Note relevant dependencies and versions.
Find related code patterns. If the decision involves a specific area (e.g., "how we handle auth"), scan for existing implementations. Identify the specific files, directories, and patterns that will be affected by the decision.
Check for ADR references in code. Look for ADR references in comments and docs (see "Code ↔ ADR Linking" below). This reveals which existing decisions govern which parts of the codebase.
Note what you found. Carry this context into Phase 1 — it will sharpen your questions and prevent the ADR from contradicting existing decisions.
Interview the human to understand the decision space. Ask questions one at a time, building on previous answers. Do not dump a list of questions.
Core questions (ask in roughly this order, skip what's already clear from context or Phase 0):
Adaptive follow-ups: Based on answers, probe deeper where the decision is fuzzy. Common follow-ups:
When to stop: You have enough when you can fill every section of the ADR — including the Implementation Plan — without making things up. If you're guessing at any section, ask another question.
Intent Summary Gate: Before moving to Phase 2, present a structured summary of what you captured and ask the human to confirm or correct it:
Here's what I'm capturing for the ADR:
- Title: {title}
- Trigger: {why now}
- Constraints: {list}
- Options: {option 1} vs {option 2} [vs ...]
- Lean: {which option and why}
- Non-goals: {what's explicitly out of scope}
- Related ADRs/code: {what exists that this interacts with}
- Affected files/areas: {where in the codebase this lands}
- Verification: {how we'll know it's implemented correctly}
Does this capture your intent? Anything to add or correct?
Do NOT proceed to Phase 2 until the human confirms the summary.
Choose the ADR directory.
contributing/decisions/ (if contributing/ exists), docs/decisions/ (MADR default), or adr/ (simpler repos).Choose a filename strategy.
YYYY-MM-DD-...), continue that.choose-database.md).Choose a template.
assets/templates/adr-simple.md for straightforward decisions (one clear winner, minimal tradeoffs).assets/templates/adr-madr.md when you need to document multiple options with structured pros/cons/drivers.references/template-variants.md for guidance.Fill every section from the confirmed intent summary. Do not leave placeholder text. Every section should contain real content or be removed (optional sections only).
Write the Implementation Plan. This is the most important section for agent-first ADRs. It tells the next agent exactly what to do. See the template for structure.
Write Verification criteria as checkboxes. These must be specific enough that an agent can programmatically or manually check each one.
Generate the file.
scripts/new_adr.js (handles directory, naming, and optional index updates).assets/templates/ and fill it manually.After drafting, review the ADR against the agent-readiness checklist in references/review-checklist.md.
Present the review as a summary, not a raw checklist dump. Format:
ADR Review
✅ Passes: {list what's solid — e.g., "context is self-contained, implementation plan covers affected files, verification criteria are checkable"}
⚠️ Gaps found:
- {specific gap 1 — e.g., "Implementation Plan doesn't mention test files — which test suite should cover this?"}
- {specific gap 2}
Recommendation: {Ship it / Fix the gaps first / Needs more Phase 1 work}
Only surface failures and notable strengths — do not recite every passing checkbox.
If there are gaps, propose specific fixes. Do not just flag problems — offer solutions and ask the human to approve.
Do not finalize until the ADR passes the checklist or the human explicitly accepts the gaps.
Agents should read existing ADRs before implementing changes in a codebase that has them. This is not part of the create-an-ADR workflow — it's a standalone operation any agent should do.
Find the ADR directory. Check contributing/decisions/, docs/decisions/, adr/, docs/adr/, decisions/. Also check for an index file (README.md or index.md).
Scan titles and statuses. Read the index or list filenames. Focus on accepted ADRs — these are active decisions.
Read relevant ADRs fully. Don't just read the title — read context, decision, consequences, non-goals, AND the Implementation Plan. The Implementation Plan tells you what patterns to follow and what files are governed by this decision.
Respect the decisions. If an accepted ADR says "use PostgreSQL," don't propose switching to MongoDB without creating a new ADR that supersedes it. If you find a conflict between what the code does and what the ADR says, flag it to the human.
Follow the Implementation Plan. When implementing code in an area governed by an ADR, follow the patterns specified in its Implementation Plan. If the plan says "all new queries go through the data-access layer in src/db/," do that.
Reference ADRs in your work. Add ADR references in code comments and PR descriptions (see "Code ↔ ADR Linking" below).
ADRs should be bidirectionally linked to the code they govern.
The Implementation Plan section names specific files, directories, and patterns:
## Implementation Plan
- **Affected paths**: `src/db/`, `src/config/database.ts`, `tests/integration/`
- **Pattern**: all database queries go through `src/db/client.ts`
When implementing code guided by an ADR, add a comment referencing it:
// ADR: Using better-sqlite3 for test database
// See: docs/decisions/2025-06-15-use-sqlite-for-test-database.md
import Database from 'better-sqlite3';
Keep these lightweight — one comment at the entry point, not on every line. The goal is discoverability: when a future agent reads this code, they can find the reasoning.
src/db/ can find which ADRs govern that areaIdentify the intent:
deprecated, explain replacement path.## More Information with a date stamp. Do not rewrite history.Use scripts/set_adr_status.js for status changes (supports YAML front matter, bullet status, and section status).
After an ADR is accepted:
contributing/decisions/2025-06-15-use-sqlite-for-test-database.md."## More Information.If the repo has an ADR index/log file (often README.md or index.md in the ADR dir), keep it updated.
Preferred: let scripts/new_adr.js --update-index do it. Otherwise:
When introducing ADRs to a repo that has none:
node /path/to/adr-skill/scripts/bootstrap_adr.js
This creates the directory, an index file, and a filled-out first ADR ("Adopt architecture decision records") with real content explaining why the team is using ADRs. Use --json for machine-readable output. Use --dir to override the directory name.
For repos with many ADRs, organize by subdirectory:
docs/decisions/
backend/
2025-06-15-use-postgres.md
frontend/
2025-06-20-use-react.md
infrastructure/
2025-07-01-use-terraform.md
Date prefixes are local to each category. Choose a categorization scheme early (by layer, by domain, by team) and document it in the index.
scripts/new_adr.js — create a new ADR file from a template, using repo conventions.scripts/set_adr_status.js — update an ADR status in-place (YAML front matter or inline). Use --json for machine output.scripts/bootstrap_adr.js — create ADR dir, README.md, and initial "Adopt ADRs" decision.references/review-checklist.md — agent-readiness checklist for Phase 3 review.references/adr-conventions.md — directory, filename, status, and lifecycle conventions.references/template-variants.md — when to use simple vs MADR-style templates.references/examples.md — filled-out short and long ADR examples with implementation plans.assets/templates/adr-simple.md — lean template for straightforward decisions.assets/templates/adr-madr.md — MADR 4.0 template for decisions with multiple options and structured tradeoffs.assets/templates/adr-readme.md — default ADR index scaffold used by scripts/bootstrap_adr.js.From the target repo root:
# Simple ADR
node /path/to/adr-skill/scripts/new_adr.js --title "Choose database" --status proposed
# MADR-style with options
node /path/to/adr-skill/scripts/new_adr.js --title "Choose database" --template madr --status proposed
# With index update
node /path/to/adr-skill/scripts/new_adr.js --title "Choose database" --status proposed --update-index
# Bootstrap a new repo
node /path/to/adr-skill/scripts/bootstrap_adr.js --dir docs/decisions
Notes:
--dir and --strategy to override.--json to emit machine-readable output.Agent 工作流
创造有效技能指南。 当用户想创造出新的技能(或更新现有的技能),以专业知识,工作流程,或工具集成来扩展克洛德的能力时,应该使用这种技能.
Agent 工作流
使用ClawdHub CLI搜索,安装,更新并发布从taladhub.com的代理技能. 需要获取苍蝇上的新技能时使用,将安装的技能同步到最新版本或特定版本,或者发布 npm-instainddhub CLI 的新/更新的技能文件夹.
Agent 工作流
管弦乐团多代理团队,任务设定周期,交接协议,审查工作流程. 使用时间: (1)建立2+特派员队伍,具有不同专业,(2)确定任务路线和生命周期(收录框_ spec_建设_审查_完成),(3)在特派员之间制定交接协议,(4)建立审查和质量关口,(5)管理特派员之间的交流和文物共享.
Agent 工作流
Spec-first,TDD,子代理驱动的软件开发工作流程. 当:(1)构建任何新功能或应用——触发脑暴_计划_子代理执行回路,(2)调试出一个bug或测试失败——触发系统性的根起过程,(3)用户说"让我们构建","帮助我计划","我想添加X",或"这个被打破",(4)完成一个功…