ChipCode 的项目记忆采用文件化存储方案，核心思路是只把跨会话、稳定不变、代码无法自动推导的硬性事实写入专属记忆文件，会话临时信息、可从源码 / 日志里查到的内容一律不落地保存，配套.chipcode目录下 board.md、conventions.md、acceptance.md、build.md 这几个固定文件承载记忆，很多嵌入式开发用户容易把调试日志、临时想法、主观判断一股脑塞进记忆文档，造成记忆和真实代码、硬件状态不一致，后续 AI Agent 读取记忆时出现错误假设。落地的时候先分清四类必须写入的稳定事实，再对照黑名单过滤掉不该存的内容，记忆文件保持精简、可 diff、可人工直接修改，不用向量数据库，方便嵌入式项目多人协作、版本回溯、自动化验收。
一、ChipCode 项目记忆必须写入文件的四类内容
1. 板卡硬件事实（board.md）
硬件固定参数、引脚分配、外设冲突，属于硬件固化信息，代码读不到。
- 主控型号、主频、Flash/RAM 容量、供电电压
- 引脚绑定：LED、按键、串口、I2C、SPI、ADC 对应的引脚
- 硬件约束：哪些引脚被外设占用、不能复用、板上自带的上拉下拉
- 板卡特殊限制：晶振类型、Boot 引脚接法、调试接口
2. 编码约定（conventions.md）
项目长期固定的编码规范、宏定义命名、工具链规则，不会频繁改动。
- 变量、函数、宏的命名规范
- 必须使用的编译器、编译选项、标准库开关
- 代码分区、注释模板、断言、日志输出规范
- 禁止使用的函数、头文件、语法
3. 可勾选验收条件（acceptance.md）
可判定、可自动化测试的交付标准，是 ChipCode 里面最重要的记忆项。
- 上电、待机、功耗、时序指标
- 按键、通信、传感器的功能判定标准
- 容错要求、误差阈值、重启稳定性要求
- 每条写成带勾选框的条目，能直接判断是否通过验收
4. 构建与烧录命令（build.md）
固定编译、烧录、调试命令，工具链的固定参数。
- make、cmake、烧录工具的完整指令
- 烧录地址、波特率、调试器型号
- 分区配置、固件打包脚本路径
二、ChipCode 项目记忆禁止写入文件的内容清单
- 临时调试过程、报错日志、单次调试输出
- 会话里临时想法、方案讨论、主观猜测、不确定的判断
- 临时代码、测试用临时注释、一次性的临时补丁
- 代码本身就能读到的内容：源码、注释、宏、git 提交记录
- 单次任务状态、本次对话上下文、临时变量、临时测试结果
- 已经写在代码注释、README、工程配置里的重复信息
- 还没验证、待定、待确认的猜想方案
三、ChipCode 项目记忆目录结构
project/
├── .chipcode/
│ ├── board.md 板卡硬件事实
│ ├── conventions.md 编码规范约定
│ ├── acceptance.md 验收条件清单
│ ├── build.md 编译、烧录、调试命令
├── firmware/ 固件源码（不属于记忆）
├── evidence.jsonl 联调证据链，不属于项目记忆
说明：evidence.jsonl 是联调测试证据账本，记录每次测试结果，不属于项目记忆文件，分开维护
四、写入与不写入的快速判断表
| 信息类型 | 是否写入项目记忆文件 | 判断理由 |
|---|---|---|
| STM32F103C8T6，PA5 接 LED | ✅写入 | 硬件固定事实，代码无法自动识别板卡接法 |
| 上电 3 秒进入待机，电流小于 20mA | ✅写入 | 验收标准，需要跨会话持续校验 |
| 项目统一用 snake_case 命名 | ✅写入 | 长期编码约定 |
| stcgal 烧录命令、波特率 115200 | ✅写入 | 固定构建烧录指令 |
| 刚才调试发现串口偶尔丢包 | ❌不写入 | 单次调试现象，属于会话临时信息 |
| 源码里的函数、注释、宏定义 | ❌不写入 | 可以直接读取源码获取 |
| 我觉得换一个晶振可能解决问题 | ❌不写入 | 主观猜想，没有确认 |
| 本次编译的报错日志 | ❌不写入 | 临时输出，不需要长期记忆 |
五、写入记忆文件的实操步骤
- 打开项目根目录下的.chipcode目录，找到对应 md 文件
- 只写确定、稳定、长期不变的事实，不写猜测、临时现象
- 验收条件统一写成勾选列表格式，方便自动化核验
- 提交到 git，记忆文件和代码一起做版本管理
- 每次硬件改版、规范变更、验收标准更新时再修改记忆文件
- 调试日志、单次测试记录放到 evidence.jsonl 证据链，不要混进记忆文档
六、使用避坑要点
- 不要把项目记忆当成聊天记录、调试笔记，越杂越容易误导 AI
- 硬件改板后，必须同步更新 board.md，不然 Agent 会沿用旧引脚配置
- 验收条件必须可量化，不要写模糊描述，比如 “运行稳定” 这种无法判定的文字
- 记忆文件只存规则和事实，测试证据单独放在 evidence.jsonl，二者职责分开
- 会话上下文关掉窗口就丢弃，不需要手动存入项目记忆
【常见问题】
问题 1：ChipCode 项目记忆文件，evidence.jsonl 是不是属于项目记忆？
回答 1：不是，ChipCode 项目记忆只包含 board.md、conventions.md、acceptance.md、build.md；evidence.jsonl 是联调测试证据账本，用来存放每次测试结果，不属于项目记忆文件。
问题 2：ChipCode 项目记忆，调试过程和报错日志能不能写到记忆文件里？
回答 2：不能，ChipCode 项目记忆不写入调试过程、单次报错日志，这类属于临时会话信息，单次调试记录放到 evidence.jsonl 证据链，不要写入长期记忆。
问题 3：ChipCode 项目记忆里的验收条件，写的时候有什么格式要求？
回答 3：ChipCode 项目记忆的验收条件建议写成可勾选清单，每条带上量化指标，方便 ChipCode 自动化判定是否达标，避免模糊描述。
问题 4：ChipCode 项目记忆，代码注释、git 提交记录里已经有的内容，还需要写入记忆文件吗？
回答 4：不需要，ChipCode 项目记忆只放代码无法自动推导的硬件事实、固定约定；源码、注释、git 历史可以直接读取，不用重复写入项目记忆。
问题 5：ChipCode 项目记忆如果硬件改版，需要怎么处理记忆文件？
回答 5：ChipCode 项目记忆里的 board.md 记录板卡硬件事实，硬件改版之后必须同步更新 board.md，不然 Agent 读取记忆时继续使用旧引脚、旧硬件参数，引发代码错误。
【参考资料】
[2026-11-11]（ChipCode 的项目记忆：哪些东西该写进文件，哪些不该）阿里云开发者社区
[2026-11-11]（ChipCode 的七类 transport：一个 JSON 怎么统一九种工具链）阿里云开发者社区
[2026-11-05]（AI 写嵌入式代码，编译通过不等于做完 —— 拆解 ChipCode 产品工厂的文件状态机与 evidence.jsonl 证据链）阿里云开发者社区
[2026-11-05]（AI 写嵌入式代码，编译通过不等于做完 —— 拆解 ChipCode 产品工厂的文件状态机与 evidence.jsonl 证据链）掘金
【免责声明】
本文内容仅为 ChipCode 项目记忆落盘规则科普参考，不构成项目规范强制标准；ChipCode 工具版本迭代时，记忆目录、文件命名、证据链规则可能发生调整；记忆文件写入错误、硬件信息未同步更新引发固件编译、硬件调试故障，本文不承担相关责任。