# 项目规范 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` | `.workhub/` | 中央接入文件：进度、视图、能力、规范副本、接入状态。由接入剧本维护，人不手改（`progress.yaml` 除外） |
| `design` | `docs/design/` | 设计文件：需求、方案、评审结论 |
| `adr` | `docs/design/adr/` | 决策记录（ADR） |
| `knowledge` | `docs/knowledge/` | 项目知识库：业务逻辑、代码结构等宏观内容 |
| `scripts` | `scripts/` | 可复用脚本：构建、部署、数据迁移、常用运维操作 |

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

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

- **映射**：不移动文件，在 `.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. 不提交账号密码、密钥、私钥、令牌、一次性脚本和本地临时文件。

---

## 对照范本

### 目录树

```text
<仓库>/
├── .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`（映射方式）

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

### `docs/knowledge/index.md`

```markdown
# <项目名> 知识库

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

## 页面

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

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

```markdown
# NNNN 标题

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

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

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

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

### `scripts/README.md`

```markdown
# 脚本

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