{"version":1,"note":"初始版本","published_by_client":"workhub","created_at":"2026-10-20T16:20:24.992962+00:00","standards":"# 项目规范 v{{ version }}\n\n> 所有接入 workhub 的项目都遵守这份规范。它规定干活的产出放在哪、怎么留存：目录怎么划分、设计文件怎么保留、脚本怎么保留、知识库怎么更新。\n> 怎么干活（流程、每个节点用哪个 agent）见 Loop 视图：{{ base_url }}/loop。\n> 规范由中央按版本维护，任何端都能发布新版本（`POST {{ base_url }}/v1/standards`）。项目里的副本是 `.workhub/standards.md`，版本记在 `.workhub/lock.yaml` 的 `standards_version`。\n\n## 一、目录划分\n\n规范按“角色”定义目录，每个角色有默认位置：\n\n| 角色 | 默认位置 | 放什么 |\n| --- | --- | --- |\n| `workhub` | `.workhub/` | 中央接入文件：进度、视图、能力、规范副本、接入状态。由接入剧本维护，人不手改（`progress.yaml` 除外） |\n| `design` | `docs/design/` | 设计文件：需求、方案、评审结论 |\n| `adr` | `docs/design/adr/` | 决策记录（ADR） |\n| `knowledge` | `docs/knowledge/` | 项目知识库：业务逻辑、代码结构等宏观内容 |\n| `scripts` | `scripts/` | 可复用脚本：构建、部署、数据迁移、常用运维操作 |\n\n代码、测试、配置按所用语言和框架的习惯放置，规范不做要求。\n\n### 已在建的项目：映射或改造，二选一\n\n- **映射**：不移动文件，在 `.workhub/layout.yaml` 里写明各角色在本项目对应的目录（格式见范本）。没写的角色用默认位置。适合目录已经稳定、不便大动的项目。\n- **改造**：按本文末尾的“对照范本”调整目录，把现有的设计文档、知识性文档、脚本归到对应位置。具体怎么迁移由 AI 根据项目实际情况处理：先列出迁移计划给人确认，再单独提交一次，不和功能改动混在一起。改造完成后不需要 `layout.yaml`。\n\n新项目直接按默认位置建目录。\n\n## 二、设计文件：记录“当时为什么这么做”\n\n1. 需求、方案、评审结论放在 `design` 目录，按主题建文件，文件名用简短的中文或英文主题词。\n2. 设计文件可以过时，但不删除。被新方案取代时，在文件开头标注“已被 `<新文件>` 取代（日期）”。\n3. 重要决策写成 ADR，放在 `adr` 目录，一个决策一个文件，文件名 `NNNN-标题.md`（编号递增）。ADR 写定后不再修改；推翻旧决策就新写一篇，并在新的里面引用旧的。\n4. 设计文件记录的是意图，代码现状以代码和知识库为准。\n\n## 三、脚本：只保留可复用的\n\n1. 以后还会再跑的脚本（构建、部署、数据迁移、常用排查）放在 `scripts` 目录，每个脚本开头写明用途、用法和参数；脚本多了在目录里放一个 `README.md` 列出清单。\n2. 一次性的脚本（某次排查、某次临时数据修复）用完即删，不提交。需要留下记录的，把结论写进设计文件、知识库或提交信息。\n3. 脚本里不写账号密码、服务器地址；需要时从 workhub 密码箱取，或读环境变量。\n\n## 四、知识库：反映业务逻辑和代码结构\n\n1. 知识库写宏观的内容：\n   - 业务：项目解决什么问题、核心业务概念和规则、关键业务流程；\n   - 结构：模块划分和各自职责、模块之间怎么协作、主要数据从哪来到哪去；\n   - 运行：怎么跑起来、怎么部署、依赖哪些外部系统；\n   - 约定：命名、分层、错误处理等项目内的约定。\n2. 更细的内容（函数怎么实现、参数含义、边界情况）写在代码注释里，需要时直接读代码。知识库不重复代码细节。\n3. 知识库描述的是“代码现在是什么样”。业务逻辑或代码结构发生变化时，在同一个提交里更新受影响的知识库页面。发现知识库与代码不一致时，以代码为准，更新知识库。\n4. 入口是 `knowledge` 目录下的 `index.md`：一段项目概述，加上各页面的目录。页面按业务领域或模块划分，不要求面面俱到，保持能读、能信即可。\n\n## 五、代码注释\n\n1. 模块（文件）开头写一段注释，说明这个模块负责什么、和谁协作。\n2. 不直观的逻辑、业务规则、边界处理、刻意的取舍，在代码旁写注释说明“为什么”。\n3. 显而易见的代码不写注释；注释随代码一起更新，过时的注释要删改。\n\n## 六、提交\n\n1. 进度变化、知识库更新和对应的代码改动放在同一个提交里。\n2. 目录改造、规范适配单独提交，提交说明写清楚做了什么。\n3. 不提交账号密码、密钥、私钥、令牌、一次性脚本和本地临时文件。\n\n---\n\n## 对照范本\n\n### 目录树\n\n```text\n<仓库>/\n├── .workhub/\n│   ├── progress.yaml          项目进度（对外公开）\n│   ├── loop.md                Loop 视图副本\n│   ├── standards.md           本规范的副本\n│   ├── layout.yaml            映射方式时才有：角色 → 本项目目录\n│   ├── lock.yaml              接入状态\n│   └── capabilities/          视图用到的 agent 和 skill\n├── docs/\n│   ├── design/\n│   │   ├── 退款流程.md         设计文件，按主题\n│   │   └── adr/\n│   │       └── 0001-退款走异步队列.md\n│   └── knowledge/\n│       ├── index.md           知识库入口\n│       ├── 业务概念.md\n│       └── 模块结构.md\n├── scripts/\n│   ├── README.md              脚本清单\n│   └── deploy.sh\n├── src/ …                     代码（按语言习惯）\n├── tests/ …\n├── AGENTS.md                  含 workhub 规则块\n└── CLAUDE.md                  第一行 @AGENTS.md\n```\n\n### `.workhub/layout.yaml`（映射方式）\n\n```yaml\n# 本项目目录与规范角色的对应。没写的角色用默认位置\nstandards_version: {{ version }}\nroles:\n  design: doc/方案\n  adr: doc/方案/决策\n  knowledge: wiki\n  scripts: tools\n```\n\n### `docs/knowledge/index.md`\n\n```markdown\n# <项目名> 知识库\n\n<一段话：这个项目解决什么问题，给谁用，核心流程是什么。>\n\n## 页面\n\n- [业务概念](业务概念.md)：<一句话>\n- [模块结构](模块结构.md)：<一句话>\n- [运行与部署](运行与部署.md)：<一句话>\n```\n\n### ADR：`docs/design/adr/NNNN-标题.md`\n\n```markdown\n# NNNN 标题\n\n- 日期：YYYY-MM-DD\n- 状态：已采纳（被推翻时写“已被 NNNN 取代”）\n\n## 背景\n<为什么需要做这个决定。>\n\n## 决定\n<决定是什么。>\n\n## 影响\n<带来的好处、代价和后续要做的事。>\n```\n\n### `scripts/README.md`\n\n```markdown\n# 脚本\n\n| 脚本 | 用途 | 用法 |\n| --- | --- | --- |\n| deploy.sh | 部署到测试环境 | `./scripts/deploy.sh <版本>` |\n```\n","agents_rules":"<!-- workhub:begin -->\n## workhub\n\n本项目接入中央工作台 workhub（{{ base_url }}），项目 ID：`{{ project_id }}`，标尺分支：`{{ branch }}`。本段由 workhub 项目规范 v{{ version }} 生成，不要手改；要更新，重新执行接入剧本 {{ base_url }}/onboarding.md。\n\n1. 开工前读 `.workhub/standards.md`（项目规范：目录、设计文件、脚本、知识库）和 `.workhub/loop.md`（流程），按它们执行；各节点用 `.workhub/capabilities/` 里对应的 agent。\n2. 改了业务逻辑或代码结构，在同一个提交里更新知识库（位置见规范，或 `.workhub/layout.yaml`）。\n3. 进度有变化时更新 `.workhub/progress.yaml`，用 `POST {{ base_url }}/v1/progress/validate` 校验后提交到 `{{ branch }}`；内容会公开，只写概括。\n4. 需要账号密码就到 workhub 密码箱取，不写进仓库、日志、提交信息；密钥从环境变量 `WORKHUB_KEY` 读取。\n5. 本项目自己的规则与上面冲突时，停下来问人。\n<!-- workhub:end -->\n"}