AI 结对开发中 Notes 与 Skills 的治理与开发指南
在 AI 主导或 AI 深度结对的中大型项目工程中，为了克服大模型的**“遗忘既有决策（上下文丢失）”与“重复复杂执行易出错（缺乏固定SOP）”**两大根本痛点，系统引入了 Notes（架构决策记录 / 项目外脑） 与 Skills（专项自动化技能 / 任务工具箱） 机制。
本文档明确定义两者在软件工程全生命周期中的定位、触发时机、自动化边界与实操开发步骤。
一、 核心定位与本质区别 (First Principles)
| 维度 | Notes (架构决策记录 ADR) | Skills (专项技能) | Rules (工程规则) |
|---|---|---|---|
| 回答的核心问题 | “为什么这样做？当初否决了什么？” | “这个复杂的多步骤任务该怎么做？” | “什么绝对不能做？代码红线是什么？” |
| 典型载体 | .agents/notes/ (Markdown) | .agents/skills/<name>/SKILL.md | .agents/rules/ (Markdown) |
| 触发方式 | 会话初始化或架构相关任务时作为上下文读取 | 任务意图匹配 description 时被 AI 自动激活调用 | 会话始终注入生效，全局刚性约束 |
| 变动频率 | 低频（仅在重大技术选型与重构研讨时增加） | 中频（随可复用工程工具与排查套路增加） | 极低（项目底线与工程哲学） |
二、 何时添加？是自动还是手动？
1. 何时添加 Notes？
- 时机一：重大架构或模型选型合入（进入
notes/implemented/）：- 例如：确定采用纯领域解耦并将追踪器从 Reader 下沉至 Core；确定采用 Swift Concurrency 并发模型；引入状态模式治理播放器复杂状态。
- 时机二：研讨否决了看似合理的方案（进入
notes/rejected/）：- 关键价值：AI 缺乏历史会话记忆，如果新开对话，AI 可能会再次提议“把某某类改成某某模式”。将否决依据记录在案，能彻底杜绝后来的 AI“重蹈覆辙”。
- 时机三：大型特性的跨会话预研提案（进入
notes/proposed/）：- 复杂功能需要多轮研讨评审时，先以提案方式留存。
自动化程度：半自动（人类确认，AI 整理草拟与落盘）
- 严禁全自动：绝对不能在每次微小的 git commit 时无脑生成 ADR，否则会产生大量信息噪音；
- 标准实践：当人类开发者与 AI 完成一轮架构探讨并敲定方案后，由人类指示“沉淀为 Note”，或 AI 在里程碑交付时主动提示“该决策属于重大架构选型，已同步整理为 ADR 落盘至 notes/”。
2. 何时添加 Skills？
- 时机一：重复发生的复杂多步骤工作流：
- 例如：发版前预检流程（检查文档镜像、执行针对性门禁测试、校验版本号递增、打包验证）；
- 例如：特定领域重构套路（消除 if-else 嵌套并提取策略模式的固定 6 步走）。
- 时机二：依赖外部专属工具链或 CLI 指令的深奥场景：
- 例如：Chrome DevTools 自动化无障碍 (a11y) 审计；Android AVD 调试；专项性能排查。
- 时机三：人类多次纠正 AI 的某类专业偏好：
- 当人类发现连续多次提醒 AI 某个专业领域的特殊规则与代码模板时，应将其提炼为 Skill。
自动化程度：手动定义为主 / AI 辅助构建（或通过
/learn提取）
- 标准实践：人类开发者感知到某类任务经常重复且提示词成本高昂，指示 AI“为这个发版/重构流程编写一个专用 Skill”，AI 按照标准目录生成
SKILL.md。
三、 Notes 的具体开发步骤与 SOP
物理目录规范：$ProjectRoot/.agents/notes/
notes/implemented/：正式落地合入的架构选型notes/rejected/：明确否决的方案（避免重蹈覆辙）notes/proposed/：预审中的架构提案
步骤 1：确立决策命名
文件命名规范：yyyy-MM-dd-简练决策短语.md
- 例：
2026-10-17-pareto-codereview-standards.md - 例：
2026-08-15-reject-swiftdata-in-core-domain.md
步骤 2：按照四段式标准模板编写
markdown
# 架构决策记录 (ADR)：[决策主题名称]
- **决策状态**: [Implemented | Rejected | Proposed]
- **决策时间**: 2026-10-17
- **决策主体**: [核心模块名称，如 Reader / Audio / Core]
---
## 一、 背景与上下文 (Context)
说明当初遇到了什么具体工程痛点、技术瓶颈或扩展性限制，促使团队必须做此决策。
## 二、 核心决策内容 (Decision)
清晰说明选用了何种技术架构、设计模式或物理下沉方案。
## 三、 否决的备选方案与原因 (Alternatives & Why Rejected)
【极为重要】列出当初研讨过的备选方案，并明确记录为什么否决它（如内存过载、引入环形依赖、心智负担过高），防止后续 AI 重蹈覆辙。
## 四、 影响与后续权衡 (Consequences)
- 正面收益：解决了什么问题、提高了多少性能/安全性。
- 潜在成本/约束：后续开发必须遵守的附带约束。步骤 3：在索引中登记
在 .agents/notes/README.md 中以相对路径登记该文件的索引超链接。
四、 Skills 的具体开发步骤与 SOP
物理目录规范：$ProjectRoot/.agents/skills/<skill_name>/
- 核心文件：
SKILL.md（必须包含 YAML Frontmatter 元数据） - 可选文件：
scripts/（配套自动化执行脚本）、examples/（参考实现）、references/（参考文档）
步骤 1：规划技能边界与触发词 (Description Engineering)
Skill 的核心在于其 YAML Frontmatter 中的 description：
- AI 是依据 description 来感知该何时加载本技能的；
- 描述中必须包含明确的触发场景、关键词与动词（例如："Use this skill when refactoring nested conditionals, applying Strategy pattern..."）。
步骤 2：创建标准目录与 SKILL.md
以新建代码设计重构技能 code-design-standards 为例：
markdown
---
name: code-design-standards
description: Instructions and best practices for applying software design patterns (Strategy, Template Method, Factory) to eliminate nested conditional branching, and maintaining documentation standards. Use when refactoring complex branching or creating extensible components.
---
# 代码设计模式重构与工程标准技能
## 技能意图
消除过深的分支嵌套（if-else / switch），指导开发者以最小心智负担落地策略与工厂模式。
## 执行工作流 (Step-by-Step Instructions)
1. 第一步：分析既有条件分支的共同抽象边界，定义协议/接口；
2. 第二步：将各分支行为封装为独立的策略实现结构体/类；
3. 第三步：通过工厂或注册表实现无分支查找与动态派发；
4. 第四步：添加针对性单元测试锁定行为保真；
5. 第五步：验证视图/逻辑缩进严格保持在 2~3 层以内。
## 禁忌与红线 (Anti-patterns)
- 严禁创建没有实质业务行为的空心协议封装；
- 严禁单次策略拆分引入超过 3 层的间接跳转。步骤 3：验证技能注册与加载
在 AI 会话中，AI 会自动扫描 customization roots 下的 skills/ 目录。当用户提问相关主题时，AI 将自主调用 view_file 读取 SKILL.md 并执行专项指令。
五、 决策速查卡片 (Cheat Sheet)
plaintext
当你在开发中产生一个想法或沉淀时：
┌─────────────────────────────────────────────────────────────┐
│ 1. 这是一个“不可打破的代码红线或设计底线”吗？ │
│ ──> 写入: .agents/rules/<name>.md并在 AGENTS.md 索引 │
├─────────────────────────────────────────────────────────────┤
│ 2. 这是一个“重大技术选型、架构分层取舍或已被否决的方案”吗？ │
│ ──> 写入: .agents/notes/<status>/<date-topic>.md │
├─────────────────────────────────────────────────────────────┤
│ 3. 这是一个“复杂但会多次重复执行的专业排查/重构/发布操作流程”吗？ │
│ ──> 创建: .agents/skills/<name>/SKILL.md │
├─────────────────────────────────────────────────────────────┤
│ 4. 这只是“本次会话的具体代码修改细节与即时回复”？ │
│ ──> 写入: logs/yyyy-MM/dd-hhmmss-$summary.md (ThinkingLog)│
└─────────────────────────────────────────────────────────────┘