Menu
识别架构决策瞬间，落盘到 docs/adr/NNNN-*.md。planner/code-reviewer 看到架构变动时自动提醒。
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Claude 用 codex CLI 做差异化对抗审查 + Layer 2 二审 + auto-fix 全链路。**v2.8.0 起流式 streaming**：codex 思考过程实时事件流（onEvent 回调每个 thread.started / item.completed / turn.completed），idle-timeout（90s 没新事件才算卡死）替代固定 totalTimeout。runCodexAudit 是 async，要 await。三层架构：Layer 1 codex (OpenAI) 流式产 finding → Layer 2 finding-validator subagent (Claude fresh) 独立复现 → Layer 3 通过自动 Edit 修不询问用户。触发：/plan 完成 / /implement 大改动 / /review 3 路并行 / /pr 4 路 PR 预检。codex 是不同模型 = 不同盲区，跟 Claude 互补不替代。**全自动 — 用户从不需要手动管 codex**。
Claude 自动接管用户级跨项目敏感配置（personal API key / 个人 PAT / git 全局身份 / 跨项目 SSH host）。触发：用户提到跨项目通用 secret、或 project-vault 检测到条目应提升到用户级、或用户问'跨项目共用 secret 放哪'。写 ~/.claude/USER_VAULT.md，hook 自动 sync 到 .user-env.{sh,ps1} + git --global + ~/.ssh/config。与 project-vault 分工：本 skill 跨项目，project-vault 单项目。
Claude 主动沉淀用户跨项目偏好到 ~/.claude/CLAUDE.md，post-hook 自动 commit+push 到 dotfiles repo 跨设备同步。触发：用户说'记下这个偏好 / 沉淀到 CLAUDE.md / 把这个习惯加进去'、用户连续多次重复同样反馈（'又忘了'）、或做了跨项目通用决策（'以后所有项目都用 zod'）。仅追加不覆盖。与 continuous-learning-v2 分工：本 skill 主动显式沉淀偏好，learning-v2 被动观察行为。
Claude 自动维护 docs/SCHEMA.md。触发：用户提到表结构（'加 users 表，字段 email/password'）、写改 ORM 模型（Prisma/SQLAlchemy/TypeORM）、写改 migration SQL、或问'数据库表结构在哪'。不存在自动建（从 ORM 抽骨架），存在直接 Edit 加表/字段；业务含义缺失填 '_TODO_' 占位。与 architecture-decision-records 分工：本 skill 记结构现状，ADR 记选型决策（如选 Postgres）。
Claude 自动维护开发实时流水日志 docs/CHANGELOG-DEV.md，记**正在发生**的需求/进度/坑/下一步。触发：用户讲新需求或改主意（◇）、Claude 完成 ≥30 行或跨文件改动（✓）、遇 blocker（⚠）、决定下一步（→）。与 git log（已落盘代码）/ ADR（终态决策）/ SCHEMA（结构）/ mistakes（bug 根因）分工——本 skill 记进行中状态。每条 ≤5 行倒序。
Claude 自动接管项目级敏感配置（API key / DB 密码 / 部署 IP / SSH / token）。触发：用户在对话里说出任何 secret 或 IP、或代码里硬编 secret、或问 '.env 怎么放 / token 存哪'。写 .claude/PROJECT_VAULT.md，hook 自动 sync 到 .env.local + .env.example + ~/.ssh/config + SECRETS-INDEX.md，强制 .gitignore。与 user-vault 分工：本 skill 单项目，跨项目用 user-vault。
| name | architecture-decision-records |
| description | 识别架构决策瞬间，落盘到 docs/adr/NNNN-*.md。planner/code-reviewer 看到架构变动时自动提醒。 |
在编码会话中捕获架构决策。决策不再只躺在 Slack / PR 评论 / 某人的脑子里，而是产出结构化 ADR 文档，和代码一起维护。
使用 Michael Nygard 提出的轻量 ADR 格式，针对 AI 辅助开发做了微调：
# ADR-NNNN: [Decision Title]
**Date**: YYYY-MM-DD
**Status**: proposed | accepted | deprecated | superseded by ADR-NNNN
**Deciders**: [who was involved]
## Context
What is the issue that we're seeing that is motivating this decision or change?
[2-5 sentences describing the situation, constraints, and forces at play]
## Decision
What is the change that we're proposing and/or doing?
[1-3 sentences stating the decision clearly]
## Alternatives Considered
### Alternative 1: [Name]
- **Pros**: [benefits]
- **Cons**: [drawbacks]
- **Why not**: [specific reason this was rejected]
### Alternative 2: [Name]
- **Pros**: [benefits]
- **Cons**: [drawbacks]
- **Why not**: [specific reason this was rejected]
## Consequences
What becomes easier or more difficult to do because of this change?
### Positive
- [benefit 1]
- [benefit 2]
### Negative
- [trade-off 1]
- [trade-off 2]
### Risks
- [risk and mitigation]
检测到决策瞬间时：
docs/adr/ 不存在，先询问用户确认再创建目录 + 索引 README.md + 空白 template.md。不经用户同意不写文件。docs/adr/ 已有 ADR 递增docs/adr/NNNN-decision-title.md；用户拒绝就丢弃草稿，不写任何文件docs/adr/README.md用户问"为什么当初选 X？"：
docs/adr/ 不存在 → 回复："项目里没有 ADR。要开始记录架构决策吗？"docs/adr/README.md 索引docs/
└── adr/
├── README.md ← index of all ADRs
├── 0001-use-nextjs.md
├── 0002-postgres-over-mongo.md
├── 0003-rest-over-graphql.md
└── template.md ← blank template for manual use
# Architecture Decision Records
| ADR | Title | Status | Date |
|-----|-------|--------|------|
| [0001](0001-use-nextjs.md) | Use Next.js as frontend framework | accepted | 2026-01-15 |
| [0002](0002-postgres-over-mongo.md) | PostgreSQL over MongoDB for primary datastore | accepted | 2026-01-20 |
| [0003](0003-rest-over-graphql.md) | REST API over GraphQL | accepted | 2026-02-01 |
显式信号
隐式信号（建议记 ADR，但别自动写，要问过用户）
proposed → accepted → [deprecated | superseded by ADR-NNNN]
| 类别 | 示例 |
|---|---|
| Technology choices | Framework, language, database, cloud provider |
| Architecture patterns | Monolith vs microservices, event-driven, CQRS |
| API design | REST vs GraphQL, versioning strategy, auth mechanism |
| Data modeling | Schema design, normalization decisions, caching strategy |
| Infrastructure | Deployment model, CI/CD pipeline, monitoring stack |
| Security | Auth strategy, encryption approach, secret management |
| Testing | Test framework, coverage targets, E2E vs integration balance |
| Process | Branching strategy, review process, release cadence |