Appearance
项目 Context、Memory 与 ADR
早期做法常常是把技术栈、目录、设备、协议、历史 Bug、临时方案、回退记录全部塞进一个 PROJECT_CONTEXT.md。短期方便，长期会出现两个问题：文件越来越大，每个小任务都加载大量无关历史；稳定业务定义和“某次修复发生过什么”混在一起，AI 很难判断哪些内容仍然有效。
V10 推荐把信息按稳定程度和用途分开。
1. 四类信息分别放哪里
| 信息 | 推荐位置 | 例子 |
|---|---|---|
| 每次都必须遵守的工程规则 | 项目 Rules / AGENTS / CLAUDE / 项目说明 | 不执行真实高压；不改协议；构建命令 |
| 稳定业务语言和概念关系 | CONTEXT.md | 测试窗口、停机窗口、自检、正式试验 |
| 项目过去发生过什么 | .agent-memory/ | 某 Bug 根因、曾经改过的文件、已知 E-SafeNet |
| 长期重要且不直观的设计取舍 | docs/adr/ | 为什么测试窗口健康检查只读缓存 |
本次任务自己的目标、NonGoals 和临时约束，留在当前任务上下文，不要全部沉淀成长期规则。
2. CONTEXT.md：只记录“这个系统里的词是什么意思”
CONTEXT.md 不是项目百科，也不是修改日志。它的目标是建立 Agent 和工程师之间的共同语言。
适合记录：
- 业务术语的标准名称；
- 容易混淆的同义词；
- 稳定的概念关系；
- 某些术语的边界和“不是什么”；
- 操作员语言与代码语言之间的映射。
不适合记录：
- “昨天修了一个 Bug”；
- 某次临时测试把频率上限放开；
- 某个 commit 的修改详情；
- 一次性的现场故障；
- 大段实现细节。
示例
markdown
# CONTEXT.md
## 测试窗口
正式试验中允许设备执行测试动作的时间段。
不要和“整轮试验”混用。
## 停机窗口
相邻测试窗口之间的停机/观察阶段。
该阶段某些设备保持连接，但不执行正式测试输出。
## 应用设备
把已确认配置写入设备，但不等同于启动正式试验。
## 自检
正式试验前验证设备、配置和基础状态的过程。
自检通过不代表真实负载条件已经验证。如果项目没有复杂业务术语，不需要为了“规范完整”强行创建几十条定义。
3. .agent-memory/：记录“以前发生过什么”
Memory 适合保存会影响后续开发效率的历史事实，例如：
- 某个 Bug 的根因和修复方式；
- 哪个测试可以验证哪类修改；
- 当前项目确认存在 E-SafeNet/Cobra DocGuard；
- 某条设备命令曾经引发双会话冲突；
- 某路径、构建方式、现场限制已经验证过；
- 某个 workaround 是否仍然有效。
推荐结构：
text
.agent-memory/
├─ pinned.md # 少量长期高价值事实
├─ index.jsonl # 可检索索引
├─ changes/YYYY-MM/ # 修改记录
├─ runtime/ # 当前任务状态
└─ cache/ # 图谱/测试/验证缓存pinned.md 应该很小
适合：
text
- 项目存在 E-SafeNet，默认构建要走已知预清策略。
- 正式日志目录为某项目约定路径。
- DHO900 RAW 恢复必须复用现有 SCPI client。不适合把所有聊天记录复制进去。
4. ADR：只记录真正值得以后解释的设计决策
Architecture Decision Record 不应该变成“每次修改写一份”。只有下面三条同时成立时才建议记录：
- 这个决定以后很难逆转；
- 如果没有上下文，后来的人会觉得这个设计很奇怪；
- 它来自一个真实的取舍，而不是普通代码实现。
例如：
text
为什么测试窗口内的高压健康检查返回缓存数据？
为什么“应用设备/自检”阶段高压目标必须保持 0 V？
为什么示波器恢复不能建立第二个 SCPI 会话？普通颜色调整、CSV 字段修改、局部 Bug 修复通常不需要 ADR。
简化模板
markdown
# ADR-00X：决策标题
## 背景
为什么需要做这个决定？
## 决策
最终选择什么？
## 备选方案
还考虑过什么？为什么没选？
## 影响
这个决定带来哪些约束、收益和代价？
## 证据
相关需求、测试、故障记录或代码位置。更多说明见 架构决策 ADR。
5. 技术栈、目录和构建命令放哪里
这类内容不属于“业务词典”，但 Agent 确实需要快速知道。
可以放在项目规则或短项目说明中，例如：
markdown
# PROJECT.md / AGENTS.md
- 技术栈：C# / .NET 8 / WPF
- Solution：src/TestPlatform.sln
- 启动项目：src/TestPlatform.App/
- 测试项目：tests/
- 默认构建：dotnet build ...
- 真实设备动作：未经人工明确授权禁止执行
- 敏感信息：客户名、IP、设备编号不得外发关键原则是：这些内容要短、稳定、可执行，不要混入大量历史故事。
6. Fast Lane 为什么默认不加载全部 Context
一个“把按钮文字改掉”的任务，如果每次都加载：
text
项目技术栈
+ 50 条业务术语
+ 过去两个月 Bug
+ 10 个 ADR
+ 全部设备限制上下文成本可能比修改本身还高。
V10 的读取原则：
text
Fast MicroPatch
→ 默认不读全部 CONTEXT / ADR / 全局 Memory
业务语义修改
→ 读取相关 CONTEXT 词条
回归 / 历史问题
→ 查相关 Memory
架构边界改变
→ 查相关 ADR不是“不使用项目知识”，而是只读取当前任务需要的项目知识。
7. 新项目怎么开始
不需要第一天就把所有文件写全。
推荐顺序：
text
先建立最小项目规则
→ 开始开发
→ 出现稳定业务术语时补 CONTEXT.md
→ 第一次遇到值得复用的历史问题时建立 .agent-memory
→ 真正发生重要设计取舍时再写 ADR这种“按需生长”比先搭一套庞大的知识库更容易长期维护。
8. 从旧 PROJECT_CONTEXT.md 迁移
如果现在已经有一个很大的 PROJECT_CONTEXT.md，可以这样拆：
| 旧内容 | 新位置 |
|---|---|
| 技术栈 / 目录 / 构建方式 | 项目规则或短项目说明 |
| 稳定业务名词 | CONTEXT.md |
| 历史 Bug / 临时方案 / 已知坑 | .agent-memory/ |
| 关键架构取舍 | ADR |
| 过期信息 | 删除或归档 |
不要为了迁移一次性重写整个项目知识库。优先拆最常被 Agent 误解、最影响效率的部分。
9. 一个完整但仍然很轻的例子
text
repo/
├─ AGENTS.md
├─ CONTEXT.md
├─ .agent-memory/
│ ├─ pinned.md
│ └─ changes/
├─ docs/
│ └─ adr/
├─ src/
└─ tests/它们分别回答：
text
AGENTS.md → AI 应该怎样工作？
CONTEXT.md → 这个系统里的词是什么意思？
.agent-memory → 以前发生过什么？
ADR → 为什么长期这样设计？10. 和 V10 Skill 配合
host-computer-dev 会优先使用项目已有的小型事实源，而不是每次重新搜索整个仓库。
相关页面：
一句话原则
Context 记录“系统是什么”，Memory 记录“以前发生了什么”，ADR 记录“为什么长期这样决定”；三者不要互相代替。