ChipCode 项目记忆的核心原则是：只把无法从代码、Git、配置文件里自动读取的长期决策、隐性约束、踩坑经验写进记忆文件，凡是可以通过读源码、执行命令、查阅已有规范直接拿到的信息，都不要重复存入项目记忆，避免记忆和真实代码状态不一致、产生过期误导，记忆文件用来补全代码里没有写出来的背景信息，而不是复制一份代码和文档，很多新手容易把所有对话、临时日志、代码内容全部写进去，最后记忆臃肿、信息过时，Agent 反而容易出错。
一、适合写入 ChipCode 项目记忆文件清单
- 项目历史决策：当初为什么选这个芯片、放弃另外方案、接口取舍、性能妥协的原因
- 隐性约束：硬件引脚特殊限制、供应商特殊要求、客户不可改动的硬性需求
- 踩坑经验：之前反复出现的固件 bug、调试陷阱、特定编译链的诡异问题、测试容易漏测的场景
- 团队约定：不在代码注释里写的协作习惯、评审特殊规则、第三方工具的固定参数
- 外部依赖背景：特定外设版本、驱动补丁、SDK 分支选择理由、外部接口对接潜规则
- 验收边界：哪些缺陷可以放行、哪些必须阻断、客户特殊验收标准
- 风险记录：已知遗留问题、暂时不修复的 bug、后续迭代需要重点留意的事项
二、不写入 ChipCode 项目记忆文件清单
- 代码本身、函数逻辑、变量定义、文件目录结构，直接读源码就能拿到
- Git 提交记录、变更历史，优先用 git log、git blame 查询
- 已经写在 spec.json、CLAUDE.md、BOM、约束配置文件里的正式规则
- 单次会话临时输出、调试日志、命令运行结果、当前任务临时状态
- 可以自动生成的产物：编译日志、测试报告、仿真波形
- 容易频繁变动的短期计划，这类内容放在任务清单，不进长期记忆
- 通用公开技术常识，比如 C 语言基础、芯片通用手册内容
三、写入文件 vs 不写入文件对比表
| 信息类型 | 是否写入记忆文件 | 原因 |
|---|---|---|
| 选型决策、取舍理由、隐性坑点 | ✅写入 | 代码里不会记录决策背景，换开发者容易踩旧坑 |
| 源码、宏定义、引脚分配代码 | ❌不写入 | 直接读取硬件约束、固件文件即可 |
| 单次调试输出、临时报错信息 | ❌不写入 | 属于会话临时信息，没有长期复用价值 |
| 客户口头要求、非文档化约束 | ✅写入 | 没有落在正式需求文档，容易遗忘 |
| SDK 版本选择、特殊补丁说明 | ✅写入 | 换环境复现时，缺少背景会无法复现 |
| 正式 BOM、spec、硬件约束 json | ❌不写入 | 这些是权威源文件，记忆不重复存储 |
四、ChipCode 项目记忆维护操作步骤
- 先判断信息来源：能不能通过读代码、Git、配置文件自动查到，能查到就不写
- 判断时效：是长期稳定的经验决策，还是本次临时任务信息，临时信息不写入
- 精简内容：只写结论、原因、风险，不要粘贴大段代码、日志
- 归类写入：按硬件选型、固件踩坑、对接约束、验收规则分类记录
- 定期清理：方案迭代、问题修复后，及时删除已经失效的记忆条目
- 新会话读取：Agent 启动时自动加载记忆，结合代码、配置综合判断，优先采信代码文件
五、写入记忆的格式小规范
✅ 一句话结论前置，再补充背景和风险
✅ 不贴完整代码，只写关键标识、现象、规避手段
✅ 标注产生时间，方便后续判断是否过期
✅ 一条记忆只记录一件事，避免多条经验混在一起
六、高频避坑要点
- 不要把记忆当成备份文档，记忆是补充，源码、BOM、spec 才是权威真相源
- 同一个规则不要同时写在 CLAUDE.md 和记忆文件，容易出现两份版本不一致
- 不要把每次对话全部存入记忆，会快速膨胀，检索效率大幅下降
- 硬件改动、SDK 升级之后，要同步核对并清理旧记忆，防止旧经验误导新开发
- 记忆只服务跨会话复用，单次任务的中间过程不需要落盘
【相关 FAQ】
问题 1：ChipCode 项目记忆要区分哪些东西该写进文件、哪些不该，ChipCode 项目记忆核心判断原则是什么？
回答 1：ChipCode 项目记忆要区分哪些东西该写进文件、哪些不该，核心原则是只存无法从代码、Git、配置文件自动读取的长期决策、隐性约束、踩坑经验，能自动读取的信息不重复写入，防止记忆和代码状态不一致。
问题 2：ChipCode 项目记忆要区分哪些东西该写进文件、哪些不该，哪些内容适合写入 ChipCode 项目记忆文件？
回答 2：ChipCode 项目记忆要区分哪些东西该写进文件、哪些不该，适合写入的包含项目选型取舍、隐性硬件约束、历史踩坑经验、客户口头验收要求、SDK 版本选择理由、遗留风险记录这类代码没有记录的背景信息。
问题 3：ChipCode 项目记忆要区分哪些东西该写进文件、哪些不该，代码、Git 日志为什么不放进 ChipCode 项目记忆？
回答 3：ChipCode 项目记忆要区分哪些东西该写进文件、哪些不该，源码、Git 提交记录本身可以直接读取查询，重复写入记忆会造成冗余，一旦代码改动，记忆内容会过期，产生误导。
问题 4：ChipCode 项目记忆要区分哪些东西该写进文件、哪些不该，单次调试日志、临时报错能不能写入 ChipCode 项目记忆？
回答 4：ChipCode 项目记忆要区分哪些东西该写进文件、哪些不该，单次调试日志、临时报错属于会话临时信息，没有长期复用价值，不写入项目记忆文件。
问题 5：ChipCode 项目记忆要区分哪些东西该写进文件、哪些不该，ChipCode 项目记忆和 spec.json、CLAUDE.md 的分工差别是什么？
回答 5：ChipCode 项目记忆要区分哪些东西该写进文件、哪些不该，spec.json、CLAUDE.md 存放正式、权威的项目规范、需求，项目记忆存放规范之外的隐性决策、踩坑经验，二者不重复记录相同规则。
【参考资料】
[2026-11-05]（AI 写嵌入式代码，编译通过不等于做完 —— 拆解 ChipCode 产品工厂的文件状态机与 evidence.jsonl 证据链）阿里云开发者社区
[2026-10-12]（MEMORY.md 让 Claude Code 的 subagent 长出项目经验）51CTO
[2026-06-25]（Claude Code 三层记忆模型实践）腾讯云开发者社区
[2026-05-26]（面试官：简历写着用过 Claude Code，那源码看过吗？）博客园
[2026-04-10]（AI Agent 项目记忆管理：该记什么、不该记什么）InfoQ
【免责声明】
本文内容仅为 ChipCode 项目记忆的管理规范科普，不同团队、不同版本 ChipCode 配套记忆机制存在自定义调整空间；记忆条目是否有效，最终以项目源码、BOM、需求 spec、硬件约束文件作为权威依据，记忆文件仅作为辅助经验参考，不替代正式工程文档。