决策笔记 BoogonClothman/boogon-agent-notes

智能体笔记

一个可移植的技能，教 AI 编程智能体在任何仓库里维护持久决策记录——记录为什么这样定、否决了哪些备选方案、以及带来了什么后果。

多数文档讲代码做什么。智能体笔记讲为什么是这样、什么方案落选了、这个决策付出了什么代价。本仓库把这套做法打包成一个 Markdown 技能，改编自 DeepSeek Harness 使用的智能体笔记系统。

中文简介

这里有什么

.agents/skills/agent-notes/
├── SKILL.md the procedure an agent follows
├── references/
│ ├── contract.md the project-facing rules; copy to .agents/notes/README.md
│ └── calibration.md worked delete/keep/archive examples
└── templates/
├── note-proposed.md
├── note-implemented.md
└── note-rejected.md
docs/
└── agent-notes-research-report.md background on the DeepSeek Harness system (Chinese)

SKILL.md 是入口。参考文档和模板只在需要时加载。

30 秒读懂核心思路

- 一条笔记，一个决策。 两个独立决策就是两条笔记，互相链接。
- 路径就是元数据。 笔记放在 {lifecycle}/{class}/yyyy-mm-dd-topic.md。在生命周期文件夹之间移动笔记就是状态变更，不需要维护索引。
- 六个固定类别。 feature、bug-fix、simplification、architecture、process、testing。这套类别属于契约的一部分：不做项目配置，不加第七个文件夹，不设 refactor 类别。
- 备选方案必填。 每条笔记都记录什么方案落选、为什么落选。备选方案只记录，不编造。
- 归档即冻结。 已实现、但不再指导后续工作的笔记，移到 archived/{class}/，由只追加的 SHA-256 清单封存。封存之后，永不编辑、翻译、移动或删除。
- 机器查结构，人来判意义。 契约规定了布局、格式、链接、配对和封存的机械检查。某条理由值不值得保留，是判断题，由校准示例提供参照。

安装

项目级（随仓库锁定版本）

New-Item -ItemType Directory -Force ".agents\skills" | Out-Null
Copy-Item -Recurse "<path-to-this-repo>\.agents\skills\agent-notes" ".agents\skills\"

mkdir -p .agents/skills
cp -R <path-to-this-repo>/.agents/skills/agent-notes .agents/skills/

提交 .agents/skills/agent-notes/。项目级副本优先于用户级副本。

用户级（所有仓库）

New-Item -ItemType Directory -Force "$HOME\.agents\skills" | Out-Null
Copy-Item -Recurse "<path-to-this-repo>\.agents\skills\agent-notes" "$HOME\.agents\skills\"

mkdir -p ~/.agents/skills
cp -R <path-to-this-repo>/.agents/skills/agent-notes ~/.agents/skills/
DeepSeek Harness 还会查找 ~/.dsh/skills/ 和 <repo>/.dsh/skills/，这两个位置都能用。.agents/skills/ 是可移植的约定，其他智能体 harness 也共用这个位置。

从 GitHub 安装

git clone https://github.com/BoogonClothman/boogon-agent-notes.git
cp -R boogon-agent-notes/.agents/skills/agent-notes ~/.agents/skills/

验证

在支持技能的智能体目录里，这个技能显示为 agent-notes。按名字调用它（支持的地方用 /agent-notes），或者直接问：

Use the agent-notes skill to record the decision behind this change.

如果它没出现，检查三件事：目录名是不是 agent-notes；SKILL.md 的 frontmatter 里 name 和 description 是否非空、是否与目录名一致；references/ 和 templates/ 是否也一起复制了——技能采纳时需要它们。

在仓库中采纳

装好技能后，让智能体采纳 Agent Notes。它会：

1. 把 references/contract.md 复制到 .agents/notes/README.md；
2. 创建 proposed/、implemented/、rejected/，每个目录下放六个固定类别，另外再建 archived/；
3. 添加目录说明和一个空的 archived/manifest.json；
4. 把这次采纳本身记为第一条 process 笔记。

之后，每遇到非平凡改动，智能体都会判断是否需要写笔记，起草前先扫一遍有没有现成的归属，最后按正确的生命周期和类别最多写一条笔记。

它不是什么

- 不是文档生成器、变更日志或任务跟踪器。
- 不是命令行工具，也不是运行时依赖。它是一套 Markdown 流程，不含任何脚本。
- 不是语义分类器。机械规则已经写明；一条笔记值不值得留，仍然要靠评审判断。

契约描述了项目应当执行的检查。本仓库不附带检查器：执行归采纳方项目负责，可以把这些检查接进自己的 CI。

设计说明

- 是流程，不是脚手架。 这个技能是一套操作流程：做什么、按什么顺序、何时停、报告什么。它不是一堆没有判断的模板。
- 类别写死。 六个类别是契约的一部分。加第七个类别属于修订契约，不是加个文件夹、改个设置或按项目约定就能了事。
- 没有集中索引。 生命周期/类别树本身就是清单；加 INDEX.md 属于违反契约。
- 历史冻结。 归档使用只追加的 manifest，后续清理无法悄悄改写记录。
- 渐进披露。 SKILL.md 承载流程；契约、校准示例和模板按需读取。

背景

研究报告记录了本技能改编自的 DeepSeek Harness 实现：它的布局、关卡、生命周期规则、归档封存，以及背后的决策。那是背景资料，不是契约。

许可与署名

MIT。见 LICENSE 和 NOTICE。
Agent Notes 体系、它的术语表，以及校准示例，都改编自 DeepSeek Harness，Copyright (c) 2026 DeepSeek, MIT。

中文简介

这是一份可移植的 Agent Notes 技能：让 AI 智能体在任意仓库里记录「为什么这样做、放弃了什么、代价是什么」，而不是把决策理由散落在代码、提交记录和聊天里。

- 结构：{lifecycle}/{class}/yyyy-mm-dd-topic.md，生命周期为 proposed / implemented / rejected，类别固定为 feature、bug-fix、simplification、architecture、process、testing 六种。
- 安装：把 .agents/skills/agent-notes/ 复制到目标项目的 .agents/skills/（随仓库锁版本），或用户级的 ~/.agents/skills/（所有项目可用）。
- 开始：在目标仓库里让智能体「用 agent-notes 技能引入 Agent Notes 机制」；它会建立 .agents/notes/，并把「引入机制」本身记成第一篇笔记。
- 边界：技能只提供流程和契约，不附带检查器；机械检查由采用它的项目接进 CI。
- 来源：改编自 DeepSeek Harness 的 Agent Notes 体系（MIT）。