ADR-NNNN: [决策标题]【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECCDate: YYYY-MM-DDStatus: proposed | accepted | deprecated | superseded by ADR-NNNNDeciders: [相关人员]Context这个决策或变更是由什么问题或情况引发的[用 2-5 句话描述当前情况、约束条件和影响因素]Decision我们提议和/或正在进行的变更是什么[用 1-3 句话清晰地陈述决策]Alternatives Considered考虑的备选方案Alternative 1: [名称]Pros: [优点]Cons: [缺点]Why not: [该选项被拒绝的具体原因]Alternative 2: [名称]Pros: [优点]Cons: [缺点]Why not: [该选项被拒绝的具体原因]Consequences影响这一变更会让哪些事情变得更容易、哪些更困难Positive[益处 1][益处 2]Negative[权衡 1][权衡 2]Risks[风险及缓解措施]模板的核心设计意图值得拆解 - **头部元信息**Date、Status、Deciders 三项构成了 ADR 的可追溯性基础。Status 字段的四个取值proposed / accepted / deprecated / superseded直接对应文档后文的 ADR 生命周期其中 superseded by ADR-NNNN 通过引用编号建立决策之间的链式关系。 - **Context 与 Decision 的篇幅约束**Context 限定 2-5 句Decision 限定 1-3 句。这不是随意设定而是与优秀 ADR 的要素中保持简短——一份 ADR 应在 2 分钟内读完的原则呼应。AI 生成内容天然容易冗长字数上限是防止 Agent 写出essay级文档的硬约束。 - **Alternatives Considered 是强制小节**每个备选方案必须同时给出 Pros、Cons 和 Why not。这一设计直接对抗我们只是选了它这种无效理由——如果某个备选方案连为何不选都写不出来说明决策本身就没有被真正论证过。 - **Consequences 三分类**Positive积极影响、Negative权衡、Risks风险与缓解措施分开列出迫使记录者诚实地面对每个决策都有代价这一事实。 ### 一个真实的 ADR 示例Redis 向量存储决策 [架构师代理文档](https://link.gitcode.com/i/4dccfae2f182448359dd10b2caa11dd4) 中给出了一个可直接对照模板的完整示例——ADR-001使用 Redis 进行语义搜索向量存储 markdown # ADR-001使用 Redis 进行语义搜索向量存储 ## 背景 需要存储和查询用于语义市场搜索的 1536 维嵌入向量。 ## 决定 使用具备向量搜索能力的 Redis Stack。 ## 影响 ### 积极影响 - 快速的向量相似性搜索10ms - 内置 KNN 算法 - 部署简单 - 在高达 10 万个向量的情况下性能良好 ### 消极影响 - 内存存储对于大型数据集成本较高 - 无集群配置时存在单点故障 - 仅限于余弦相似性 ### 考虑过的替代方案 - **PostgreSQL pgvector**速度较慢但提供持久化存储 - **Pinecone**托管服务成本更高 - **Weaviate**功能更多但设置更复杂 ## 状态 已接受 ## 日期 2025-01-15这个示例展示了三个值得注意的实践点其一决策陈述非常具体——Redis Stack而非某个向量数据库其二消极影响与积极影响同样翔实包括仅限于余弦相似性这样的功能性限制其三替代方案清单给出了拒绝理由慢、贵、复杂而不是简单罗列。这三者恰好就是优秀 ADR 的要素中具体明确诚实地陈述后果包含被拒绝的备选方案三条准则的落地。工作流程捕获新 ADR 的 8 步闭环技能的工作流程章节给出了从检测到归档的完整操作序列共 8 步初始化仅首次如果docs/adr/不存在需先征求用户确认然后创建目录、一个以索引表头预置的README.md格式见下文以及一个供手动使用的空白template.md。未经明确同意不得创建任何文件——这是贯穿全文的权限边界即使 Agent 检测到了决策信号文件系统写入也必须经过用户授权。识别决策从对话中提取正在做出的核心架构选择。收集上下文是什么问题引发了此决策存在哪些约束条件记录备选方案考虑了哪些其他选项为什么拒绝了它们陈述后果权衡是什么什么会变得更容易/更难分配编号扫描docs/adr/中现有的 ADR 编号并递增即 NNNN 取当前最大编号 1。确认并写入先向用户展示 ADR 草稿供审查仅在获得明确批准后才写入docs/adr/NNNN-decision-title.md如果用户拒绝丢弃草稿、不写入任何文件。更新索引将新条目追加到docs/adr/README.md。这条工作流有两个设计精髓一是**草稿先行、批准后写的两阶段提交模式把 Agent 的生成能力与写入权限彻底分离从根本上避免了 AI 擅自改动仓库二是编号递增**保证了 ADR 序列的稳定性——即使某条 ADR 后来被弃用其编号也不会被复用从而保证索引中的引用永不失效。读取现有 ADR 的流程当用户问我们为什么选择了 X时技能定义了与写入对称的只读流程检查docs/adr/是否存在若不存在回复このプロジェクトでADRが見つかりません。アーキテクチャ決定の記録を始めたいですか该项目中未找到 ADR是否要开始记录架构决策若存在扫描docs/adr/README.md索引寻找相关条目读取匹配的 ADR 文件向用户呈现 Context 与 Decision 小节若未找到匹配项回复その決定についてのADRが見つかりません。今すぐ記録しますか未找到关于该决策的 ADR是否现在记录。注意这里的呈现范围是 Context 和 Decision——即先给出为什么和是什么两个最核心的信息而不是把整份 ADR 倾倒给用户体现了面向阅读效率的设计。目录结构与索引格式ADR 日志的组织方式技能文档规定了标准的目录布局docs/ └── adr/ ├── README.md ← 所有 ADR 的索引 ├── 0001-use-nextjs.md ├── 0002-postgres-over-mongo.md ├── 0003-rest-over-graphql.md └── template.md ← 供手动使用的空白模板README.md作为索引采用如下 Markdown 表格格式# Architecture Decision Records | ADR | Title | Status | Date | |-----|-------|--------|------| | 0001 | Use Next.js as frontend framework | accepted | 2026-01-15 | | 0002 | PostgreSQL over MongoDB for primary datastore | accepted | 2026-01-20 | | 0003 | REST API over GraphQL | accepted | 2026-02-01 |文件名遵循NNNN-decision-title.md的约定如0001-use-nextjs.md编号与索引表格一一对应。这个结构解决了三个实际问题可发现性索引表一屏总览全部决策、可链接性superseded by ADR-NNNN可以精确指向替换文档、可扩展性新 ADR 只需追加一行索引无需维护复杂元数据。从仓库现状看docs/下目前尚未出现adr/子目录这也印证了技能中首次使用时需初始化并征得用户同意的设计——ADR 日志是由团队按需启动的工程资产而不是仓库自带的默认设施。决策检测信号Agent 如何识别决策时刻为了让捕获流程的第 1 步真正可自动化技能将对话中的决策信号分为显式与隐式两类。显式信号用户直接表达决策意图让我们选择 X我们应该使用 X 而不是 Y权衡是值得的因为……将此记录为 ADR隐式信号建议记录 ADR但未经用户确认不得自动创建比较两个框架或库并得出结论做出数据库模式设计选择并陈述理由在架构模式之间选择单体 vs 微服务、REST vs GraphQL决定身份验证/授权策略评估备选方案后选择部署基础设施。显式与隐式的区分非常关键显式信号意味着用户已经在做决策陈述Agent 可以直接进入捕获流程而隐式信号只是决策正在发生的旁证Agent 的正确动作是主动建议记录 ADR把决定权交还给用户。这条规则与 8 步工作流中的初始化需确认写入需批准一起构成了完整的Agent 可建议、不可擅动权限模型。优秀 ADR 的要素写作质量准则技能用Do / Dont对照表定义了 ADR 的质量边界。应该做具体明确——使用 Prisma ORM而不是使用一个 ORM。具体到产品名而非类别名是 ADR 有用性的第一前提记录原因——理由比内容更重要the rationale matters more than the what包含被拒绝的备选方案——未来的开发者需要知道考虑了哪些选项诚实地陈述后果——每个决策都有权衡隐藏代价等于伪造记录保持简短——一份 ADR 应在 2 分钟内读完使用现在时态——我们使用 X而不是我们将使用 X。现在时表明决策是当前生效的事实而非尚未兑现的计划。不应该做记录琐碎的决定——变量命名或格式化选择不需要 ADR写成论文——Context 部分超过 10 行就太长了省略备选方案——我们只是选了它不是有效的理由追溯记录而不加标记——如果记录过去的决定必须注明原始日期让 ADR 过时——被取代的决策应引用其替代品。这些准则对 AI 辅助写作尤其有约束力Agent 生成内容时天然倾向于信息堆砌而2 分钟可读完Context 不超过 10 行现在时态这些可校验的硬标准正是对抗生成式冗长与时态漂移的有效手段。ADR 生命周期决策状态的演进与退役技能定义了 ADR 的状态机proposed → accepted → [deprecated | superseded by ADR-NNNN]【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考