Back to Details

agent-decision-log

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Decision Log

决策日志

What this skill does

此技能的作用

This skill creates institutional memory for codebases. It works as a loop:
  1. Read — Before starting work, check for existing decisions and let them shape your approach
  2. Work — Build what the user has asked for
  3. Write — Record the significant decisions you made and why
Without this loop, every agent session starts from zero. The code shows what was built, but not why it was built that way, what alternatives were considered, or what tradeoffs were accepted. Over time, this creates codebases where nobody — human or machine — can explain the rationale behind key choices.
This skill fixes that. Decisions persist between sessions. The agent that works on this project tomorrow benefits from the reasoning of the agent that worked on it today.
该技能为代码库创建组织记忆，通过以下循环运作：
  1. 查阅 — 开始工作前，检查是否存在过往决策，并以此指导你的工作方式
  2. 执行 — 完成用户要求的任务
  3. 记录 — 记录你所做出的重要决策及其原因
如果没有这个循环，每次Agent会话都要从零开始。代码能展示最终实现，但无法体现为何如此构建、考虑过哪些替代方案，或是做出了哪些取舍。长此以往，代码库会变得无人能解释关键选择的背后逻辑——无论是人类开发者还是AI Agent。
该技能解决了这个问题。决策会在会话间持久化。明天处理该项目的Agent将受益于今天处理项目的Agent的推理过程。

Step 1: Read existing decisions

步骤1：查阅过往决策

At the start of every task, check whether 
DECISIONS.md
exists in the project root.
If it exists, read it before doing anything else. These are decisions made by previous agents or developers. They represent accumulated reasoning about this specific project and should be treated seriously.
When reading existing decisions:
  • Note active constraints. If a previous decision chose a specific library, pattern, or architecture, your work should be consistent with that choice unless there is a strong reason to change it.
  • Identify relevant context. Previous decisions often contain rationale that applies to your current task, such as "we chose this database because the client needs multi-currency support later." That context should inform how you approach related work.
  • Look for conventions. The collection of decisions often reveals implicit standards (error handling patterns, naming conventions, architectural style) even when no single decision states them explicitly.
  • Check for staleness. If a decision references a constraint that no longer applies (a library that has been removed, a requirement the user has since changed), note this but do not silently ignore the decision. Flag it in your new records.
If it does not exist, that is fine. Proceed with the task and create the file when you make your first significant decision.
在每项任务开始时，检查项目根目录下是否存在
DECISIONS.md
文件。
若文件存在，在开展任何工作前先阅读它。这些是由之前的Agent或开发者做出的决策，代表了针对该特定项目积累的推理过程，应予以重视。
阅读过往决策时：
  • 注意有效约束：如果之前的决策选择了特定库、模式或架构，你的工作应与该选择保持一致，除非有充分的理由进行变更。
  • 识别相关上下文：过往决策通常包含适用于当前任务的理由，例如“我们选择该数据库是因为客户后续需要多币种支持”。这些上下文应指导你处理相关工作的方式。
  • 寻找约定俗成的规范：一系列决策往往能揭示隐含的标准（错误处理模式、命名规范、架构风格），即使没有单个决策明确说明这些标准。
  • 检查是否过时：如果某个决策引用的约束已不再适用（例如已移除的库、用户已更改的需求），请记录这一点，但不要默默忽略该决策。在你的新记录中标记此情况。
若文件不存在，无需担心。继续执行任务，当你做出第一个重要决策时创建该文件。

How previous decisions should influence your work

过往决策应如何影响你的工作

Previous decisions are strong defaults, not rigid constraints. Follow this hierarchy:
  1. Respect by default. If a previous decision is relevant to your current task, follow the established approach unless the user's request directly conflicts with it or you have a clear technical reason not to.
  2. Ask when uncertain. If the user's request seems to conflict with a previous decision, mention the conflict and ask how they want to proceed before overriding it. For example: "There's an existing decision to use Zod for validation across the project. Your request uses Joi. Would you like me to stick with Zod for consistency, or switch to Joi and update the decision log?"
  3. Supersede when justified. If you have a clear reason to change direction, do it — but write a new decision record that explicitly supersedes the old one and explains what changed. Never silently contradict a previous decision.
过往决策是强有力的默认规则，而非刚性约束。请遵循以下优先级：
  1. 默认遵循：如果过往决策与当前任务相关，请遵循既定方式，除非用户的请求直接与之冲突，或是你有明确的技术理由不遵循。
  2. 不确定时询问：如果用户的请求似乎与过往决策冲突，请提及该冲突，并在替代之前询问用户希望如何处理。例如：“项目中已有使用Zod进行验证的决策。你的请求要求使用Joi。请问我应保持使用Zod以保证一致性，还是切换为Joi并更新决策日志？”
  3. 有充分理由时替代：如果你有明确的理由改变方向，可以进行变更——但需撰写新的决策记录，明确替代旧决策并解释变更原因。切勿默默与过往决策相悖。

Step 2: Work on the task

步骤2：执行任务

Build what the user has asked for. As you work, be aware of the decisions you are making. Not every line of code involves a decision worth recording, but many tasks involve at least one significant choice. Stay alert for the moments described in the "When to write a record" section below.
完成用户要求的任务。工作过程中，留意你所做出的决策。并非每一行代码都值得记录，但许多任务至少涉及一个重要选择。请留意下文“何时记录”部分所述的场景。

Step 3: Write new decision records

步骤3：撰写新的决策记录

After implementing a decision (not before — you need to know what you actually did), append a record to 
DECISIONS.md
in the project root. Create the file if it does not exist, using the template in 
references/DECISIONS_TEMPLATE.md
.
在完成决策的实施后（而非之前——你需要记录实际执行的内容），将记录追加到项目根目录下的
DECISIONS.md
文件中。如果文件不存在，使用
references/DECISIONS_TEMPLATE.md
中的模板创建该文件。

The Y-Statement format

Y-Statement格式

Every decision record follows the Y-statement format, an established convention in software architecture. It captures the essential elements of a decision in a single structured statement.
Short form (for straightforward decisions):
In the context of [situation], facing [concern], we decided for [option] to achieve [quality], accepting [downside].
Long form (preferred when the decision is complex or consequential):
In the context of [situation], facing [concern], we decided for [option] and neglected [alternatives], to achieve [desired outcome], accepting [downside], because [rationale].
Each field serves a purpose:
  • Context: The use case or task that prompted the decision. Ground this in what you were actually asked to do.
  • Concern: The specific tension, constraint, or competing requirement you faced.
  • Decision: What you chose. Be specific about the pattern, library, structure, or approach.
  • Alternatives neglected: What you genuinely considered but rejected. Do not fabricate alternatives to make the record look thorough.
  • Desired outcome: The quality attribute the decision serves — extensibility, performance, simplicity, security, maintainability, etc.
  • Downside accepted: What you knowingly gave up. Every decision has a cost; name it.
  • Rationale: Additional reasoning, especially context from the user's requirements that influenced the choice.
每条决策记录均遵循Y-Statement格式，这是软件架构领域的既定规范。它通过结构化语句捕捉决策的核心要素。
简短格式（适用于简单决策）：
在[场景]的背景下，面对[顾虑]，我们决定采用[方案]以实现[目标]，同时接受[弊端]。
详细格式（决策复杂或影响重大时首选）：
在[场景]的背景下，面对[顾虑]，我们决定采用[方案]并放弃[替代方案]，以实现[预期结果]，同时接受[弊端]，原因是[理由]。
每个字段的作用：
  • 背景：触发决策的用例或任务。请基于实际收到的请求进行描述。
  • 顾虑：你面临的具体矛盾、约束或相互冲突的需求。
  • 决策：你选择的具体方案。请明确说明模式、库、结构或方法。
  • 放弃的替代方案：你真正考虑过但最终拒绝的选项。请勿编造替代方案来让记录看起来更全面。
  • 预期结果：决策旨在实现的质量属性——可扩展性、性能、简洁性、安全性、可维护性等。
  • 接受的弊端：你明知需要付出的代价。每个决策都有成本，请明确说明。
  • 理由：补充的推理过程，尤其是用户需求中影响选择的上下文。

Record template

记录模板

markdown
undefined
markdown
undefined

[Short title describing the decision]

[描述决策的简短标题]

Date: YYYY-MM-DD Status: Accepted Files: [key files created or changed]
In the context of [situation], facing [concern], we decided for [option] and neglected [alternatives], to achieve [desired outcome], accepting [downside], because [rationale].

See `references/examples.md` for worked examples across different decision types, including superseding previous decisions and referencing earlier decisions in new work.
日期： YYYY-MM-DD 状态： 已接受 文件： [创建或修改的关键文件]
在[场景]的背景下， 面对[顾虑]， 我们决定采用[方案] 并放弃[替代方案]， 以实现[预期结果]， 同时接受[弊端]， 原因是[理由]。

请查看`references/examples.md`中的不同决策类型示例，包括替代过往决策以及在新工作中引用早期决策的示例。

When to write a record

何时记录

Write a decision record when you:
  • Create a new module, service, or significant file structure
  • Choose a library, framework, or external dependency
  • Design or modify a data model, schema, or database structure
  • Define an API contract or endpoint pattern
  • Make a security-related choice (authentication, data handling, access control)
  • Make a performance tradeoff (caching, query optimisation, data structure choice)
  • Choose between meaningfully different implementation approaches
  • Introduce a pattern that will be repeated across the codebase
  • Deviate from an existing convention in the codebase
  • Supersede or contradict a previous decision in the log
Do NOT write a record for:
  • Bug fixes where the fix is obvious from the error
  • Formatting or linting changes
  • Renaming for clarity
  • Minor refactors that do not change behaviour or structure
  • Changes where there was only one reasonable option
When in doubt: "Would a developer joining this project in six months benefit from knowing why I did this?" If yes, write the record.
在以下场景中撰写决策记录：
  • 创建新模块、服务或重要文件结构
  • 选择库、框架或外部依赖
  • 设计或修改数据模型、模式或数据库结构
  • 定义API契约或端点模式
  • 做出与安全相关的选择（认证、数据处理、访问控制）
  • 做出性能取舍（缓存、查询优化、数据结构选择）
  • 在有显著差异的实现方式中进行选择
  • 引入将在代码库中重复使用的模式
  • 偏离代码库中已有的规范
  • 替代或与日志中的过往决策相悖
请勿在以下场景中撰写记录：
  • 修复明显的bug（可从错误中直接看出修复方式）
  • 格式调整或代码规范检查的变更
  • 为提升清晰度进行的重命名
  • 不改变行为或结构的小型重构
  • 只有一个合理选项的变更
如有疑问，请自问：“六个月后加入项目的开发者是否需要知道我为何这样做？”如果答案是肯定的，请撰写记录。

Superseding previous decisions

替代过往决策

When a new decision contradicts or replaces an earlier one, do two things:
  1. Update the old record's status:
markdown
**Status:** Superseded by "Title of new decision"
  1. In the new record, add a Supersedes field and explain what changed. See Example 7 in 
    references/examples.md
    for a worked example.
当新决策与早期决策相悖或替代早期决策时，请执行两项操作：
  1. 更新旧记录的状态：
markdown
**状态：** 被“新决策标题”替代
  1. 在新记录中添加替代字段，并解释变更内容。请查看
    references/examples.md
    中的示例7了解具体实现。

Writing guidelines

撰写指南

Write after implementing, not before. You need to record what you actually did, not what you planned to do.
Keep records concise. A good record is 3-8 lines. The Y-statement format is deliberately compact. If you are writing paragraphs, you are overexplaining.
Use plain language. Write for a developer who understands the codebase but was not present for this session. Avoid jargon specific to the current conversation.
Reference the user's requirements when relevant. If the user said something that directly shaped the decision ("we will need multi-currency support later"), include it in the rationale. This is exactly the context that gets lost between sessions.
Do not fabricate alternatives. Only list options you genuinely considered. If the choice was straightforward, say so.
Group related decisions. If a single task involves multiple connected decisions, write them as separate records or combine them if tightly coupled. Use your judgement.
完成实施后再记录。你需要记录实际执行的内容，而非计划要做的内容。
保持记录简洁。优质记录通常为3-8行。Y-Statement格式故意设计得简洁紧凑。如果你在撰写段落，说明你过度解释了。
使用平实语言。为了解代码库但未参与本次会话的开发者撰写记录。避免使用仅适用于当前对话的行话。
相关时引用用户需求。如果用户的某些表述直接影响了决策（例如“我们后续需要多币种支持”），请将其纳入理由部分。这些正是会话间容易丢失的上下文信息。
请勿编造替代方案。仅列出你真正考虑过的选项。如果选择非常明确，请如实说明。
将相关决策分组。如果单个任务涉及多个相互关联的决策，请将它们作为单独记录撰写，或在紧密耦合时合并。请自行判断。

Working in teams

团队协作

When multiple engineers are working in the same repo with their own agents, decisions will be written on separate branches. This is fine. The single-file approach means git will occasionally produce merge conflicts on 
DECISIONS.md
, but these are trivial to resolve because each record is an independent block of text.
The more important issue is not merge conflicts but contradictory decisions. Two agents on different branches might make opposite choices without knowing about each other. One chooses Zod, the other chooses Joi. Both write valid records. This is actually useful — when the branches merge, the contradiction is visible in the log in a way it would not be visible in the code alone.
Follow these practices when working on a branch:
  • Check for upstream changes. Before making a significant decision, check whether 
    DECISIONS.md
    on the main branch has been updated since your branch was created. If new decisions have been added that are relevant to your current work, read them and account for them.
  • Note your branch context. If you are aware that your work is happening in parallel with other active branches, mention this in your decision record. For example: "This decision was made on branch feature/auth-redesign. If other branches have made related choices about session management, those should be reconciled at merge time."
  • Flag decisions that need team alignment. Some decisions are local to a feature and safe to make independently. Others affect the whole codebase and should not be made in isolation. If you are making a decision that could conflict with work happening elsewhere (choosing a major dependency, changing a shared data model, altering an API contract), note it clearly so reviewers catch it during PR review.
When reviewing pull requests, check the decision records alongside the code. If two PRs contain conflicting decisions, resolve the conflict before merging and update the losing record's status to superseded.
当多名工程师在同一仓库中使用各自的Agent工作时，决策将被记录在不同分支上。这是正常现象。单文件方式意味着git偶尔会在
DECISIONS.md
上产生合并冲突，但这些冲突很容易解决，因为每条记录都是独立的文本块。
更重要的问题并非合并冲突，而是相互矛盾的决策。不同分支上的两个Agent可能在不知情的情况下做出相反的选择：一个选择Zod，另一个选择Joi，两者都撰写了有效的记录。这实际上是有用的——当分支合并时，日志中的矛盾会显现出来，而这在代码中是无法直接看到的。
在分支上工作时，请遵循以下实践：
  • 检查上游变更：做出重要决策前，检查主分支上的
    DECISIONS.md
    自你的分支创建以来是否有更新。如果添加了与当前工作相关的新决策，请阅读并考虑这些决策。
  • 记录分支上下文：如果你知道自己的工作与其他活跃分支并行进行，请在决策记录中提及此情况。例如：“此决策是在feature/auth-redesign分支上做出的。如果其他分支在会话管理方面做出了相关选择，应在合并时进行协调。”
  • 标记需要团队对齐的决策：有些决策是特定功能的本地决策，可以独立做出；而其他决策会影响整个代码库，不应孤立做出。如果你做出的决策可能与其他地方的工作冲突（例如选择主要依赖、更改共享数据模型、修改API契约），请明确标记，以便评审者在PR评审时注意到。
在评审拉取请求时，请同时检查决策记录和代码。如果两个PR包含相互矛盾的决策，请在合并前解决冲突，并将被替代的记录状态更新为“已替代”。

What this is not

此技能的适用边界

Not a changelog. This does not record every change. The git history does that. This records the reasoning behind significant choices.
Not a design document. This does not describe the full architecture. It captures individual decision points. Over time, the collection tells the story of how the architecture evolved and why.
Not an ADR process. Traditional Architecture Decision Records are heavyweight documents created through a deliberate review process. This is lighter and more continuous — decisions are captured in the flow of work, not as a separate activity.
不是变更日志：不会记录每一项变更——git历史已经做到了这一点。该技能记录的是重要选择背后的推理过程。
不是设计文档：不会描述完整架构——它捕捉的是单个决策点。随着时间推移，一系列记录会讲述架构如何以及为何演变的故事。
不是ADR流程：传统的架构决策记录（ADR）是通过刻意评审过程创建的重量级文档。该技能更轻量、更持续——决策是在工作流程中捕捉的，而非作为单独的活动。