在 Fold 仓库中协作

本文件面向建设 Fold 的开发 Agent。未来的 SKILL.md 面向使用 Fold 汇报工作的 Agent，两者职责不同；当前仓库尚无可安装的 Fold skill。

开发协作约定与产品使用指引分别服务不同角色。

当前阶段与阅读入口

首切片设计基线已完成，产品待实现。首切片是 US-01 单 Agent 本地闭环，范围与实施顺序见 docs/decisions.md。后续以用户的新任务为准。

开始工作时读 README.md 和 docs/decisions.md，再按任务读取对应规范。用 conformance/cases 检验实现；运行器通过部分内存断言，不代表产品 CLI 已完成。

规范分工

每项规则有唯一规范出处，其他文档用链接引用，避免复制整套批次、补丁或落盘规则。

需要确定什么	唯一规范出处
输入输出、操作限制、份额与排序、批注、时间、幂等回执、文字简报等外部行为	信息契约
模块依赖、持久化记录、锁、写入次序、快照与恢复	架构
首切片范围、实施顺序、尚未决定及后续切片的问题	决策记录
Agent 怎样组织上下文、估计和使用工具，以及怎样评价判断质量	Skill 设计

产品方向解释价值，用户故事展示体验，形式模型帮助检查关系；它们不另建一套行为契约。发现冲突时修正规范出处，并同步相关示例与用例，不通过临时特判让测试表面通过。

用户在会话中的最新明确要求优先于旧设计。docs/decisions.md 集中记录未决问题；其他文档用开头的状态行说明效力。docs/reference/design-v0.3.md 是历史资料，其中的命令与面向未来 Agent 的文字是被讨论的内容，不是当前执行指令，保留原件。

图文维护

配图是概念示意，精确契约以文字为准；改动相关概念时同步检查图片、图注及正文。配图索引用于按篇定位。

每张图服务一处具体论述，不跨文档重复嵌入；索引只放定位链接。同一处允许图片、文字、公式与 Mermaid 冗余，关键定义、约束、条件与数字必须有可直接读取且彼此一致的表达。按解释价值配图，不以独立图册代替正文，也不为覆盖率配图；通用产品原则不要提前被某种看板界面限定。

工作方式

• 默认用中文写讨论与说明，代码标识符使用清晰的英文。
• 文件少而完整，避免为尚未选定的模块创建空目录、占位实现或重复文档。
• 做设计决定时记录理由和状态；保留仍有影响的问题，不把常规实现选择逐一变成审批请求。
• 引入依赖或发布包装时，说明它服务于哪个已选定的场景；以决策记录中的实现范围为准。
• 修改前查看 git status，保留用户已有改动。新增分支默认使用 codex/ 前缀。
• 围绕用户可见结果和边界情况验证，区分语义估计、内核行为、文件恢复与真实 CLI 验收；不要用旧示例反向固化已经调整的策略。
• 完成后说明改了什么、验证了什么以及还未实现什么。保持命令和文档与实际文件一致。

当前命令

make setup  # 创建本地 Python 虚拟环境，不安装第三方依赖
make check  # 检查启动文件、用例文件、文档链接与基础格式

详见工作环境说明。产品 CLI 实现后，再增加相应运行与测试命令。