项目规范 v1

所有接入 workhub 的项目都遵守这份规范。它规定干活的产出放在哪、怎么留存：目录怎么划分、设计文件怎么保留、脚本怎么保留、知识库怎么更新。 怎么干活（流程、每个节点用哪个 agent）见 Loop 视图：https://workhub.qianba.cc/loop。 规范由中央按版本维护，任何端都能发布新版本（POST https://workhub.qianba.cc/v1/standards）。项目里的副本是 .workhub/standards.md，版本记在 .workhub/lock.yaml 的 standards_version。

一、目录划分

规范按“角色”定义目录，每个角色有默认位置：

代码、测试、配置按所用语言和框架的习惯放置，规范不做要求。

已在建的项目：映射或改造，二选一

• 映射：不移动文件，在 .workhub/layout.yaml 里写明各角色在本项目对应的目录（格式见范本）。没写的角色用默认位置。适合目录已经稳定、不便大动的项目。
• 改造：按本文末尾的“对照范本”调整目录，把现有的设计文档、知识性文档、脚本归到对应位置。具体怎么迁移由 AI 根据项目实际情况处理：先列出迁移计划给人确认，再单独提交一次，不和功能改动混在一起。改造完成后不需要 layout.yaml。

新项目直接按默认位置建目录。

二、设计文件：记录“当时为什么这么做”

1. 需求、方案、评审结论放在 design 目录，按主题建文件，文件名用简短的中文或英文主题词。
2. 设计文件可以过时，但不删除。被新方案取代时，在文件开头标注“已被 <新文件> 取代（日期）”。
3. 重要决策写成 ADR，放在 adr 目录，一个决策一个文件，文件名 NNNN-标题.md（编号递增）。ADR 写定后不再修改；推翻旧决策就新写一篇，并在新的里面引用旧的。
4. 设计文件记录的是意图，代码现状以代码和知识库为准。

三、脚本：只保留可复用的

1. 以后还会再跑的脚本（构建、部署、数据迁移、常用排查）放在 scripts 目录，每个脚本开头写明用途、用法和参数；脚本多了在目录里放一个 README.md 列出清单。
2. 一次性的脚本（某次排查、某次临时数据修复）用完即删，不提交。需要留下记录的，把结论写进设计文件、知识库或提交信息。
3. 脚本里不写账号密码、服务器地址；需要时从 workhub 密码箱取，或读环境变量。

四、知识库：反映业务逻辑和代码结构

1. 知识库写宏观的内容：
   • 业务：项目解决什么问题、核心业务概念和规则、关键业务流程；
   • 结构：模块划分和各自职责、模块之间怎么协作、主要数据从哪来到哪去；
   • 运行：怎么跑起来、怎么部署、依赖哪些外部系统；
   • 约定：命名、分层、错误处理等项目内的约定。
2. 更细的内容（函数怎么实现、参数含义、边界情况）写在代码注释里，需要时直接读代码。知识库不重复代码细节。
3. 知识库描述的是“代码现在是什么样”。业务逻辑或代码结构发生变化时，在同一个提交里更新受影响的知识库页面。发现知识库与代码不一致时，以代码为准，更新知识库。
4. 入口是 knowledge 目录下的 index.md：一段项目概述，加上各页面的目录。页面按业务领域或模块划分，不要求面面俱到，保持能读、能信即可。

五、代码注释

1. 模块（文件）开头写一段注释，说明这个模块负责什么、和谁协作。
2. 不直观的逻辑、业务规则、边界处理、刻意的取舍，在代码旁写注释说明“为什么”。
3. 显而易见的代码不写注释；注释随代码一起更新，过时的注释要删改。

六、提交

1. 进度变化、知识库更新和对应的代码改动放在同一个提交里。
2. 目录改造、规范适配单独提交，提交说明写清楚做了什么。
3. 不提交账号密码、密钥、私钥、令牌、一次性脚本和本地临时文件。

对照范本

目录树

<仓库>/
├── .workhub/
│   ├── progress.yaml          项目进度（对外公开）
│   ├── loop.md                Loop 视图副本
│   ├── standards.md           本规范的副本
│   ├── layout.yaml            映射方式时才有：角色 → 本项目目录
│   ├── lock.yaml              接入状态
│   └── capabilities/          视图用到的 agent 和 skill
├── docs/
│   ├── design/
│   │   ├── 退款流程.md         设计文件，按主题
│   │   └── adr/
│   │       └── 0001-退款走异步队列.md
│   └── knowledge/
│       ├── index.md           知识库入口
│       ├── 业务概念.md
│       └── 模块结构.md
├── scripts/
│   ├── README.md              脚本清单
│   └── deploy.sh
├── src/ …                     代码（按语言习惯）
├── tests/ …
├── AGENTS.md                  含 workhub 规则块
└── CLAUDE.md                  第一行 @AGENTS.md

.workhub/layout.yaml（映射方式）

# 本项目目录与规范角色的对应。没写的角色用默认位置
standards_version: 1
roles:
  design: doc/方案
  adr: doc/方案/决策
  knowledge: wiki
  scripts: tools

docs/knowledge/index.md

# <项目名> 知识库

<一段话：这个项目解决什么问题，给谁用，核心流程是什么。>

## 页面

- [业务概念](业务概念.md)：<一句话>
- [模块结构](模块结构.md)：<一句话>
- [运行与部署](运行与部署.md)：<一句话>

ADR：docs/design/adr/NNNN-标题.md

# NNNN 标题

- 日期：YYYY-MM-DD
- 状态：已采纳（被推翻时写“已被 NNNN 取代”）

## 背景
<为什么需要做这个决定。>

## 决定
<决定是什么。>

## 影响
<带来的好处、代价和后续要做的事。>

scripts/README.md

# 脚本

| 脚本 | 用途 | 用法 |
| --- | --- | --- |
| deploy.sh | 部署到测试环境 | `./scripts/deploy.sh <版本>` |

<!-- workhub:begin -->
## workhub

本项目接入中央工作台 workhub（https://workhub.qianba.cc），项目 ID：`<project_id>`，标尺分支：`<标尺分支>`。本段由 workhub 项目规范 v1 生成，不要手改；要更新，重新执行接入剧本 https://workhub.qianba.cc/onboarding.md。

1. 开工前读 `.workhub/standards.md`（项目规范：目录、设计文件、脚本、知识库）和 `.workhub/loop.md`（流程），按它们执行；各节点用 `.workhub/capabilities/` 里对应的 agent。
2. 改了业务逻辑或代码结构，在同一个提交里更新知识库（位置见规范，或 `.workhub/layout.yaml`）。
3. 进度有变化时更新 `.workhub/progress.yaml`，用 `POST https://workhub.qianba.cc/v1/progress/validate` 校验后提交到 `<标尺分支>`；内容会公开，只写概括。
4. 需要账号密码就到 workhub 密码箱取，不写进仓库、日志、提交信息；密钥从环境变量 `WORKHUB_KEY` 读取。
5. 本项目自己的规则与上面冲突时，停下来问人。
<!-- workhub:end -->