# 项目协作规范（项目级模板）

> 项目级规范 + 项目组级规范引用。**开始任何任务前：先读本文件，再读项目组级规范。**
> 本文件是**唯一根级文档**，同时担任工作区索引：三大类目录索引见 §3。
> 版本: v1.2 ｜ 最近修订: 2026-09-19 ｜ 变更记录见文末。
> **本文件是本项目的规范性规则，不是参考资料**——偏离按偏差处理，不按偏好权衡。

## 0. 项目组级规范（依赖声明）

- 位置：`../shared-standards/AGENTS.md`（与本工作区同级、在工作区之外，**只读引用**）。
- **路径基准（全项目统一）**：本文件与配套文档里出现的一切路径，**一律相对项目根**
  （即本工作区根目录）。这样文档无论被移到哪一层都不会失效。
- 该文件**不在本工作区内**，因此 DSH 的会话指令注入不会包含它——本文件只是指向它，
  由代理按需读取；引用一律相对路径，不复制正文（见 §6 指针化条款）。
- 本文件夹由 `project-template` 复制而来：新项目 = 复制本文件夹到 project-group 下
  并改名，以**独立工作区**在 DSH 打开；`../shared-standards/` 相对路径自动成立。
- 优先级（两档制）：项目组级 TOP 规则为最高优先级、**不可覆盖**；其余组级条款为
  默认值，本项目覆盖时须在本文件 §2 显式写明理由；冲突时以项目组级规范为准。
- 更新项目组级规范：本工作区无写入权限（workspace-write 只覆盖本工作区）；
  需要更新时走**提权通道**——对越界写操作申请一次性权限并说明理由，
  经用户批准后执行；日常使用一律只读，不合并目录、不复制双份。

## TOP 规则（抄自项目组级规范，压缩后仍存活；细节以项目组级规范为准）

1. 未签目标书不立项；未批计划书不执行。
2. 一个单元=一个分支=一个会话；收单元七步打勾缺一不可。
3. 请示用户一律用提问卡片。
4. 闸没过完禁止进入下一单元。
5. 里程碑完成第一时间总结+推送到远端仓库。

## 1. 项目定位（占位）

- 项目：`<一句话项目定位>`
- 当前阶段：`<当前阶段>`

## 2. 本项目特有规则（项目级补充，冲突以项目组级规范为准）

- `<占位：本项目特色规范，遇新规则沉淀于此>`

## 3. 目录分类索引（三大类）

> 根级文档只有本文件（AGENTS.md），其余全部归入三大类；
> **每个类别文件夹内自行维护内部索引（各自 README.md）**。

| 类别 | 目录 | 语义 | 子结构 |
|---|---|---|---|
| 一、输入素材 | `inputs/` | 项目获得的外部材料 | `user/`（用户提供：`materials/` 资源、`tools/` 工具）；`ai/`（AI 调研：`reports/` 报告、`data/` 数据）——均按文件类型/内容分组 |
| 二、过程工程 | `process/` | 项目进行中的工程与文档 | `tmp/`（临时垃圾文件）；`project/`（正式工程：`scripts/`、`configs/`）；`docs/`（文档**实例区**，含 `docs/plans/` 目标书与计划书、`docs/spec-proposals/` 规约提案）；`templates/`（文档**模板区**，含 `templates/plans/`） |
| 三、输出产物 | `outputs/` | 交付与沉淀成果 | 产物类型由本项目自定：**先在本区 README 登记一行，再建同名子目录**；不预置类型 |

- `process/tmp/`：可随时清空；归档/打包时整体剔除。
- `process/templates/` 为文档**模板区**（`<名>.template.md` 永为模板）；`process/docs/` 为
  **实例区**（实例骨架已预置，填内容参考 templates/ 对应模板，可随时复制覆盖重置）。
- 合规与工程规范（standards.md）在项目组级：`../shared-standards/standards.md`。

## 4. 状态

- [ ] 目标定义书（process/docs/plans/goal-spec.md）已填写并签名
- [ ] 计划书（process/docs/plans/plan.md）已批准
- [ ] `<项目阶段清单>`

## 5. 快速导航

| 目的 | 位置 |
|---|---|
| **新会话接续** | `process/docs/HANDOFF.md` |
| **项目组级规范（只读）** | `../shared-standards/AGENTS.md` |
| 工作日志 | `process/docs/work-log.md` |
| **★施工文档（交付版）** | `process/docs/construction.md` |
| 决策记录 | `process/docs/decisions.md` |
| **目标定义书** | `process/docs/plans/goal-spec.md` |
| **计划书与门禁表** | `process/docs/plans/plan.md` |
| 进度看板（多角色模式） | `process/docs/progress.md` |
| 单元文件夹与角色交接 | `process/docs/units/`、`process/docs/handoff/` |
| **多角色流水线规约（组级，只读）** | `../shared-standards/pipeline-and-roles.md` |
| 假设登记 | `process/docs/assumptions.md` |
| 实测记录 | `process/docs/measurements.md` |
| 文档模板区（格式参考） | `process/templates/` |
| 规约修订提案 | `process/docs/spec-proposals/` |
| 项目配置（用户填） | `process/project/configs/project-config.toml` |

## 6. 规约反作用与文档初始化

- **反作用（修改规约）**：要分析/完善项目规约时，开一个**专用会话**（先读规约 → 分析完整性 →
  讨论确认 → 按组级 AGENTS.md §9 流程落地）；日常干活会话不混入规约修改。
- **文档初始化**：`process/templates/` 为模板区（含格式示例）；`process/docs/` 实例骨架已预置，
  填内容时参考对应模板；需要重置可复制模板（去掉 `.template` 后缀）覆盖实例。
- **本文件体量与指针化**：本文件会被 DSH 每个会话开局注入（连同项目根到工作目录沿途的
  全部 `AGENTS.md`，合计上限 65536 字节）；超出时先整体丢弃较宽的文件、最后才截断最具体的
  文件。因此本文件只做**索引与指针**：项目特有规则需要展开时，正文写进 `process/docs/`
  下的独立文档，此处只留一行指向它；**禁止把组级规范正文复制进来**（第二份副本即分叉
  起点，且会占满注入额度）。参考上限：20 KB 以内。
- **先确定你的角色**（任何预设都适用）：本项目按角色分工。若你是用**角色预设**启动的，
  角色已由 persona 给定，直接采用；否则**先用提问卡片请用户指定角色**，再往下走。
  三个角色（制作人 / 实现者 / 验收员）的**写权范围与各闸读档顺序**在组级
  `../shared-standards/pipeline-and-roles.md` 里——那是唯一真源，本文件不复制它。
  **多角色是可选能力**：不用角色时按单会话流程走组级 `AGENTS.md` §7，本文件同样适用。
- **项目内技能**：`.agents/skills/project-flow/SKILL.md` 是本项目的操作技能（开局触发、
  给出读档顺序）。技能只做触发与指针，正文仍在上述组级文件里。
  项目级技能根有两个（`.dsh/skills` 与 `.agents/skills`，DSH 均自动发现），本项目选后者：
  `.dsh` 是用户级 harness home（`~/.dsh`）的目录名，项目级再用它会让项目资产与工具状态同名。
- **并行前提**：同一工作目录同一时刻只有一个活跃写入会话（`git checkout` 按目录生效、
  协作文档为追加或覆盖写）；需要并行时，先在计划书的单元定义里写明该单元预期触碰的
  文件与目录集合，文件集不相交才可并行（见组级 AGENTS.md §6）。

## 变更记录

| 日期 | 版本 | 变更 | 批准 |
|---|---|---|---|
| 2026-09-16 | v1.0 | 首次版本化：补版本头与变更记录；§0 修正相对路径描述并注明组级规范不参与会话注入；§3 补 `docs/plans/`、`docs/spec-proposals/`、`templates/plans/` 并改为产物类型不预置；§5 补目标书、计划书、假设、实测四行；§6 新增本文件体量与指针化、并行前提 | 用户 |
| 2026-09-16 | v1.1 | 顶部补「本文件是本项目的规范性规则，不是参考资料」（不依赖任何预设的效力声明）；§5 导航补进度看板、单元文件夹与角色交接、组级多角色规约三行；§6 新增「先确定你的角色」（任何预设都适用：由 persona 给定或提问卡片确认）、指向组级唯一真源、声明多角色为可选能力，并补项目内技能 `project-flow` 的位置与"只做触发与指针" | 用户 |
| 2026-09-19 | v1.2 | §6 项目内技能路径 `.dsh/skills/` → `.agents/skills/`，并写明选择理由（项目级技能根有两个，`.dsh` 是用户级 harness home 的目录名）。**为何通用**：本条只管"项目内智能体资产用哪个目录名"，与项目领域、技术栈无关；`.dsh` 撞名是 DSH 自身的命名事实，任何用该模板的项目都受同一影响。防的事故（频率×损失）：项目级 `.dsh/` 与用户级 `~/.dsh` 同名，容易被读成"工具状态目录"；为防该误读而设的 `.gitignore` 规则（`.dsh/*` + `!.dsh/skills/`）会把该目录下除技能外的文件**静默**排除出 git（每建一个新项目都在，损失为文件静默不入库）。改用 `.agents/` 后该规则整条删除，项目资产默认入库 | 用户 |