Project Building

让下一位协作者只需阅读少量入口文件，就能知道项目目标、当前状态、操作方法和下一步，并能追溯重要决定的依据。

使用边界

• 区分用户要讨论流程、初始化项目、推进实现，还是整理交接。讨论只交付方案；只读检查只汇报；明确要求建设或维护时再写文件。
• 用户已授权推进项目时，相关文档维护属于工作的一部分，不要求用户逐份确认。发布、推送、停止作业等操作仍遵循本次任务的授权范围。
• 先沿用项目已有结构；按缺口补充，不为套用本 skill 搬迁目录、改技术栈或新增工具。
• 不把一个项目的服务器地址、训练参数、版本目录或历史事故变成所有项目的规则。

文档写作：必须使用内置 better-notes

凡本流程涉及编写或修改文档，包括 AGENTS.md、HANDOFF、索引、设计、进度、实验记录与知识笔记，必须先读取并执行 references/document-writing.md。该文件会加载内置的 better-notes/SKILL.md 及其必读参考资料；不能只看规则摘要或模板就直接写作。

内置包包含 better-notes 的完整正文、参考资料、示例、验证脚本和评估场景，无需另行安装 better-notes，也不依赖原目录。按文档对象加载论文与 Obsidian 分支，用户和目标项目的明确要求优先。只读检查和纯代码修改不因此加载全部写作资料。

1. 接手：先还原实际项目

读取适用的 AGENTS.md、根 README、PROJECT_HANDOFF.md、docs 索引及本次任务相关设计。查看实际代码入口、构建配置和已有改动；需要运行信息时核对进程、日志和产物，不能只转述旧文档。

确定本次目标、已有成果、必要约束和可验证的完成标准。已有信息足够就推进；只有缺失信息会改变工作范围或关键方案时才询问。

文档与代码冲突时，区分“期望设计”和“实际行为”。保留差异及来源，不能把现有实现直接写成用户已批准的设计。

2. 建立入口：规则、现状、证据分开存放

默认提供下面四个入口；已有等价文件时直接沿用并建立链接，不再维护另一套。

创建或修订 AGENTS.md 前读取 references/agents-guide.md，按 assets/AGENTS.template.md 裁剪填写。交接使用 assets/HANDOFF.template.md。生成的文件要写入已核实的信息，删除不适用章节；未知内容明确标注待确认，不填猜测命令。

按设计版本组织：v0 起步，每版三个核心文件 + guides/

新项目从 docs/v0/ 开始；用户确认下一轮设计迭代后，依次建立 docs/v1/、docs/v2/。目录统一使用小写 v。docs/README.md 作为全局索引，说明各版本目标、状态、承接关系和当前工作版本，并链接对应入口。

每个版本采用下面的三个核心文件和按需建立的 guides/。多模块项目可按实际需要使用 docs/<模块>/v0/ 等层级；已有版本号和等价结构时沿用，不重编号或擅自搬迁。

版本号对应用户确认的设计迭代。当前方案内的修复、补充验证和日常进展更新当前版本，不因一次提交或一次实验自动升版。进入新版本时，在新版本 README 中说明相对上一版的目标与主要变化，DESIGN 记录新版本有效设计，PROGRESS 从本轮迭代开始记录；保留旧版本设计、进展和证据，并链接前后版本。根 PROJECT_HANDOFF.md 同步当前工作版本及其入口。不要提前创建尚未开始的版本目录。

新建同一模块或版本的文档时，先判断能否更新这三个核心文件；需要单独展开的材料放 guides/，避免在同级堆放 FINAL、DESIGN_v2、review、summary 等文档。指南中的有效结论要同步到 DESIGN 或 PROGRESS，并从 README 或相关核心段落提供入口。被替代的方案标明历史状态及其后继，不把草案和现行设计混在一起。

实验配置、原始结果、日志和权重仍放实际实验或产物目录，guides/ 只放说明或分析并链接证据。已有等价结构时沿用，不擅自搬迁历史文件；不要预建空目录和大量占位文档。

若方法设计在 Obsidian 或其他外部位置，明确其权威范围和路径。仓库文档记录实现映射与差异，并链接原设计；相同事实尽量只维护一份。

3. 推进：把问题变成可验证的改动

根据实际需要执行设计、实现和验证，不为每个小改动强制增加提案或审查阶段。

• 重要方案写清问题、选择理由、关键接口或行为、完成标准。记录影响后续判断的取舍，不记录每一次闲聊。
• 先检查已有代码与可复用能力，再做范围内的最小充分改动。简洁性和代码约定见 AGENTS 指南。
• 验证实际行为及重要边界；测试、构建、真实运行或界面检查按任务选择。不要只验证新文件存在，或让测试复制实现逻辑。
• 验证未能执行时，记录未验证的范围与原因；“已实现”“测试通过”“已部署”“运行完成”分别陈述。
• 发现故障时，修复前核实根因；修复后留下现象、根因、修复、验证。假设尚未证实时明确说明。

研究或长时间运行任务另读 references/research-projects.md。普通开发不需要套用实验流程。

4. 沉淀：保存重要决定和可追溯证据

一个重要进展应让读者回答：

发生了什么问题？为什么这样做？实际改了什么？如何验证？结果支持什么？下一步是什么？

按内容选用这些字段，不要求每条记录填满模板。数值结论链接到对应产物或生成脚本；运行状态附检查时间与时区；推断与直接观测分开写。

失败的尝试也保留必要结论和条件，避免重复验证同一个猜想。新证据推翻旧结论时，给旧结论标注已被替代并链接新记录，保留历史依据。

详细日志、配置、数据和图表放已有的实验或产物目录；docs 负责解释并提供入口。代码生成的评分、排名或报告通过原脚本更新，不能手改数据迎合文字结论。

5. 同步：按变化更新对应文件

不要每次都改所有文件。只读状态查询不能借此写文档；普通小修不需要建立独立决策文档。长任务在阶段完成、重要状态变化、切换任务或交接前及时更新，避免全部留到最后。

维护 HANDOFF 时以当前状态为主，详细历史移到现有专题记录；避免同一文件上半部分说“已停止”、下半部分又说“正在运行”。仅能引用历史快照时注明时间，不写成当前确认状态。

6. 收尾：让结果能检查、让工作能继续

交付前检查：

• 文档中的路径、命令和链接是否对应实际项目；新命令是否已执行验证，未验证处是否明确。
• 本次的重要改动、判断和证据是否有入口；旧约束与用户已有内容是否保留。
• 文档是否已按内置 better-notes 完成来源核对、语言准确性检查和去 AI 味编辑，编辑是否保留技术事实与真实不确定性。
• 当前状态和下一步是否一致；运行中的作业是否有可定位的标识和恢复入口。

最终回复简短说明完成内容、文件入口、验证结果及剩余问题。需要时报告部署、提交或推送状态，不自动执行发布或 Git 操作。