---
name: project-building
description: 建立和持续维护项目的工作方式与文档体系。用户要求创建 AGENTS.md、建立 docs、整理项目交接、沉淀开发或实验流程，或按已有项目规范推进工作时使用。编写或修改文档必须使用内置的 better-notes，核对来源、语言准确性和写作风格。适用于软件和研究项目；单纯概念问答、独立文件编辑或只读状态查询不因此自动触发项目文档写入。
---

# Project Building

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

## 使用边界

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

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

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

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

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

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

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

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

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

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

| 入口 | 记录内容 | 不放什么 |
| --- | --- | --- |
| 根 AGENTS.md | 项目目标、目录地图、环境、命令、代码约定、真实操作约束、文档入口 | 每次运行的 PID、实时分数、完整历史 |
| 根 PROJECT_HANDOFF.md | 截至什么时间的现状、进行中事项、主要问题、下一步、证据入口 | 逐次操作流水和整段日志 |
| docs/README.md | 按主题组织的文档索引和当前工作入口 | 与专题文档重复的结果正文 |
| docs/ 内的专题文档 | 设计、实现说明、阶段进展、实验分析和重要决定 | 大体积原始数据、权重、敏感信息 |

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

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

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

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

| 文件或目录 | 职责 | 维护方式 |
| --- | --- | --- |
| README.md | 模块或版本的总览、当前状态摘要、使用入口、文档导航 | 保持简短，链接 DESIGN、PROGRESS 和相关 guides，不复制详细正文 |
| DESIGN.md | 当前有效的设计、关键接口、实现映射和已知差异 | 方案定案或实现变化时更新；旧方案和长篇讨论放 guides |
| PROGRESS.md | 按日期记录推进过程、重要决定、实验结果、问题与修复验证 | 保留历史，写清为何改变方案，并链接详细证据 |
| guides/ | 中间方案、审查意见、探索记录、专题分析、操作指南和历史设计快照 | 按主题命名，材料增多后再建主题子目录；需要区分时间的材料带日期 |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

| 本次发生的变化 | 应维护的入口 |
| --- | --- |
| 操作命令、路径、环境或长期约束变化 | AGENTS.md 和受影响的使用说明 |
| 设计、接口或实际行为变化 | 对应 DESIGN 或专题文档；必要时记录与总设计的差异 |
| 实验完成、重要决定、故障与修复 | 对应 PROGRESS 或实验记录 |
| 当前状态、阻塞或下一步变化 | PROJECT_HANDOFF.md |
| 新增专题或工作入口变化 | docs/README.md；必要时更新根 README |

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

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

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

交付前检查：

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

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