项目记录规范（V10）

项目记录的目标不是把每次 AI 对话完整保存下来，而是让未来的人或 Agent 能快速回答：

以前发生过什么？
为什么这样设计？
这条业务术语是什么意思？
这次修改到底验证了什么？

记录应该减少未来返工，而不是成为当前任务的固定负担。

1. 先决定：这次任务值得记录吗？

任务	默认记录策略
Read-Only Trace，只查当前行为	不建任务记录
文案/颜色/Margin 等 MicroPatch	Git Diff 足够，通常不额外记录
普通明确功能修改	只保留简短 Change Summary + Verification
BehaviorPatch	记录 Behavior Contract 和关键验证
RegressionFix	记录 known-good、根因证据、修复和防回归点
ExperimentalChange	记录临时范围、正式规则是否保持、恢复方法
E-SafeNet/现场环境坑	值得进入 .agent-memory
长期架构/业务取舍	满足条件才写 ADR
新稳定业务术语	必要时更新 CONTEXT.md

不要为了“规范”给一个 Label 改字也创建一份 2 页记录。

2. 四类信息不要混在一个大文档里

当前任务记录
= 这次要做什么、实际改了什么、证据是什么

.agent-memory/
= 以后可能再次遇到的历史修复、环境坑、局部事实

CONTEXT.md
= 稳定业务术语和概念关系

ADR
= 为什么做了一个长期重要、难反转且不直观的取舍

不要重复保存

例如：

• “停机窗口”的稳定定义 → CONTEXT.md；
• “某次 Race 是如何修掉的” → .agent-memory；
• “为什么测试窗口内高压健康查询只读缓存” → 如果满足 ADR 三条件，可写 ADR；
• 当前这次把 15 A 改 16 A → 当前任务/Diff，不需要复制到四个地方。

详见 项目 Context、Memory 与 ADR。

3. 一个普通任务最小记录就够了

推荐：

Date:
Task:
Target:
NonGoals:
Changed:
VerificationLevel:
VerifiedEvidence:
Unverified:
EnvironmentBlocked:
HardwarePending:

例如：

Date: 2026-08-26
Task: 充电电流上限 15 A → 16 A
Target: 正式业务约束统一为 16 A
NonGoals: 不改其它电源参数，不改变通信协议
Changed: UI / Application validation / MES validation / DeviceApply guard
VerificationLevel: V2
VerifiedEvidence: affected build + HighCurrentLimitTests 6/6
Unverified: None
EnvironmentBlocked: None
HardwarePending: RealHardware

这比保存几十轮聊天更有长期价值。

4. BehaviorPatch 应记录“规则”，不是聊天过程

推荐保留：

Trigger:
Condition:
Action:
Reset:
Record:
NonGoals:

例如：

Trigger: 停机窗口采样
Condition: 连续 5 个有效帧超过阈值
Action: AlarmOnly，不 Stop
Reset: 正常帧清零；下一窗口重新计数
Record: 5 帧 RawPeak + 工程值 + 时间戳
NonGoals: 不改示波器模式和下一测试窗口

然后补：

VerificationLevel: V3
FocusedTests: Verified
WorkflowSmoke: Verified
Hardware: NotRequired

不必把 AI 第一次误解的整个回答都长期保存。

5. RegressionFix 记录时间差和根因证据

近期回归最值得沉淀的是：

Symptom:
KnownGood:
IntroducedBy:
BehaviorDelta:
RootCauseEvidence:
Fix:
RegressionSignal:
Invariant:

例如：

Symptom: RAW 恢复后示波器偶发会话冲突
KnownGood: commit abc123
IntroducedBy: recovery branch change
BehaviorDelta: 恢复路径新建第二 SCPI client
RootCauseEvidence: captured session log + diff
Fix: 复用当前 SCPI session
RegressionSignal: replay + focused test
Invariant: 同一示波器恢复流程不得并发创建第二 session

这种内容值得进入 .agent-memory，因为以后能直接阻止同类错误。

6. ExperimentalChange 必须留下恢复信息

临时边界试验至少记录：

ExperimentalScope:
OfficialRulePreserved:
SafetyInterlockPreserved:
EntryPoint:
RestoreMethod:
Expires/ExitCondition:
Verification:

测试结束后能回答：

哪一处是临时改的？怎么恢复？正式规格有没有被污染？

否则临时改动很容易半年后变成没人敢删的正式逻辑。

7. 验证记录必须区分四种状态

不要只写：

测试通过

推荐区分：

Verified
Unverified
EnvironmentBlocked
HardwarePending

例如：

AffectedBuild: EnvironmentBlocked(E-SafeNet)
FocusedTests: Verified 8/8
Replay: Verified
RealHardware: HardwarePending

这样不会把环境失败说成代码失败，也不会把没测真机说成全部验证完成。

8. 真机验证只记录实际发生的事实

涉及真实设备时记录：

• 设备角色/必要型号；
• 软件版本/配置；
• 实际执行的动作；
• 目标值和持续时间；
• 现场操作者确认；
• 真实结果；
• 日志/截图/波形等证据；
• 没有执行的动作。

如果没做真实高压输出，就写：

HardwarePending: 2 kV 输出未执行

不能因为软件侧 Fake 通过就在研制总结里写“真机验证通过”。

详见 真实设备操作与验证安全边界。

9. 什么值得进入 .agent-memory

适合：

• 重复出现过的局部 Bug 根因；
• 特定设备的重要会话/协议特性；
• E-SafeNet 等环境问题的已验证处理方式；
• 某项目稳定且以后会反复用到的路径/测试映射；
• 关键 invariant。

不适合：

• 一次性 UI 文案；
• 已经从代码能快速确认的普通事实；
• 大段聊天；
• AI 未验证的猜测；
• 临时 debug 输出。

Memory 应短、可检索、能在未来减少搜索。

10. 什么值得进入 CONTEXT.md

只放稳定业务语言，例如：

测试窗口
停机窗口
预充阶段
应用设备
测量单元

写：

• 定义；
• 与其它术语关系；
• 容易混淆的概念。

不要放：

• 类名；
• 文件路径；
• 当前 TODO；
• 某次 Bug 的修复步骤；
• “今天改了什么”。

11. ADR 只在三个条件同时满足时写

1. Hard to reverse；
2. Surprising without context；
3. Real trade-off。

满足才记录：

Context
Decision
Alternatives
Consequences
Invariant

普通 bugfix、UI 样式、易回退实现，不需要 ADR。

12. 不要默认保存完整 Prompt

以下内容通常没有长期价值：

• 第一次给 AI 的完整 Prompt；
• AI 第一版错误方案全文；
• 每一轮“继续”；
• 反复搜索过程；
• 已经被最终方案淘汰的临时推测。

如果某段 Prompt 真正形成了稳定、反复可用的方法，再抽象成模板或 Skill；不要把聊天原文当知识库。

13. 项目结束后只问三个沉淀问题

1. 这次有没有以后很可能再次遇到的事实/坑？
   → Memory

2. 有没有稳定业务术语被重新定义或澄清？
   → CONTEXT

3. 有没有长期且难反转的设计取舍？
   → ADR

都没有，就让 Git 历史和正常任务记录结束这次工作，不需要为了“有沉淀”创造沉淀。

14. 一份高价值记录的判断标准

至少满足一项：

• 能帮助以后更快定位同类问题；
• 能解释一个长期不直观设计；
• 能阻止未来再次犯同一业务错误；
• 是正式交付/验收所需证据；
• 能明确尚未验证的风险。

否则通常没有必要长期保存。

下一步

• 项目 Context、Memory 与 ADR
• AI 开发验证体系
• 技术文档工程
• V10 Skill 说明

一句话原则

保留结论、边界和证据，删除流水账；只有未来真的能减少搜索、返工或争议的信息，才值得进入长期项目知识。