# 开发环境创建指南

创建人员：Codex  
文件职责：指导项目管理员在具体项目中创建默认开发体系根目录，以及按需为某个目标体系创建开发工作区。  
管理规范/模板：../../全局规范.md；编码规范.md；开发审计规范.md。  
引用文件：编码规范.md；编码方案范本.md；开发事项总纲模版.md；开发事项计划模版.md；开发执行日志模版.md；开发审计报告模版.md；开发问题记录模版.md。  
记录方式：创建指南；开发体系目录、模板或创建流程变化时更新。

## 1. 使用场景

本指南有两个使用场景：

1. 项目创建时，由项目环境创建流程自动调用本指南，创建默认开发体系根目录和根级开发账本。
2. 项目后续需要写代码时，按本指南为具体目标体系创建目标开发工作区。

开发体系默认随项目创建，但目标开发目录按需创建。

```text
项目创建时默认创建：
dev/
dev/test/
dev/tmp/
dev-doc/
dev-doc/目录导读.md
dev-doc/编码规范.md
dev-doc/开发审计规范.md
dev-doc/开发事项总纲.md
dev-doc/开发事项计划.md
dev-doc/开发执行日志.md
dev-doc/开发审计报告.md
dev-doc/开发问题记录.md

启用某个目标开发时再创建：
dev/<target>-dev/
dev/<target>-dev/test/
dev/<target>-dev/tmp/
dev-doc/<target>-doc/
```

## 2. 创建前需要确认的信息

| 项 | 说明 |
|---|---|
| project_root | 项目根目录 |
| creation_mode | root_default / target_workspace |
| target_system | 目标体系：pro / exp / ana / project / data / other；root_default 可填 ROOT |
| target_dev_key | 开发目录名，例如 pro-dev、exp-dev、ana-dev |
| dev_owner | 默认开发 AI 或人工 |
| dev_auditor | 默认开发审核员 |
| upstream_entry | 上游需求、实验设计、案例设计、项目事项计划或聊天记录 |
| flow_weight | light / heavy；是否需要编码方案 |

项目创建时使用 `creation_mode = root_default`，不需要 target_dev_key。

如果后续目标体系没有启用，但确实需要项目工具开发，可使用 `project-dev`。

## 3. 目录结构

### 3.1 项目默认开发体系根目录

```text
<project_root>/
  dev/
    test/
    tmp/
  dev-doc/
    目录导读.md
    编码规范.md
    开发审计规范.md
    开发事项总纲.md
    开发事项计划.md
    开发执行日志.md
    开发审计报告.md
    开发问题记录.md
```

### 3.2 目标开发工作区

```text
<project_root>/
  dev/
    <target>-dev/
      test/
      tmp/
  dev-doc/
    <target>-doc/
      目录导读.md
      开发工作区说明.md
      开发方案/
```

示例：

```text
需求开发：dev/pro-dev/、dev/pro-dev/test/、dev-doc/pro-doc/
实验开发：dev/exp-dev/、dev/exp-dev/test/、dev-doc/exp-doc/
案例分析开发：dev/ana-dev/、dev/ana-dev/test/、dev-doc/ana-doc/
```

## 4. 项目级文件职责

| 文件 | 来源 | 职责 |
|---|---|---|
| `dev-doc/目录导读.md` | 可手写 | 说明项目默认开发体系的入口和当前状态 |
| `dev-doc/编码规范.md` | 本地规范 | 引用 common `编码规范.md`，记录项目根级开发补充 |
| `dev-doc/开发审计规范.md` | 本地审计规范 | 引用 common `开发审计规范.md`，记录项目根级开发审计补充 |
| `dev-doc/开发事项总纲.md` | `开发事项总纲模版.md` | 根级开发事项背景、目标、边界、状态和结论滚动账本 |
| `dev-doc/开发事项计划.md` | `开发事项计划模版.md` | 根级开发计划、步骤、输入输出、验收方式和审计入口 |
| `dev-doc/开发执行日志.md` | `开发执行日志模版.md` | 根级实际编码、测试、自检和偏离记录 |
| `dev-doc/开发审计报告.md` | `开发审计报告模版.md` | 需求开发、项目工具开发、独立开发事项的方案审核、实现审核、测试验收和复审 |
| `dev-doc/开发问题记录.md` | `开发问题记录模版.md` | 根级非审计来源开发问题闭环 |
| `dev-doc/<target>-doc/目录导读.md` | 可手写 | 说明目标开发工作区的入口和当前事项 |
| `dev-doc/<target>-doc/开发工作区说明.md` | 可手写 | 说明目标开发目录、代码入口、测试入口、所属事项和根级账本回写位置 |
| `dev-doc/<target>-doc/开发方案/` | 按需创建 | 存放重型开发事项的具体编码方案文件；轻量开发可不创建具体方案 |

一个项目只有一套开发体系账本。开发事项总纲、计划、执行日志和问题记录默认登记到 `dev-doc/开发事项总纲.md`、`dev-doc/开发事项计划.md`、`dev-doc/开发执行日志.md`、`dev-doc/开发问题记录.md`。审计报告入口按目标体系分账：需求开发、项目工具开发、独立开发事项写 `dev-doc/开发审计报告.md`；实验开发写 `exp-doc/实验审计报告.md`；案例分析开发写 `ana-doc/案例审计报告.md`。`dev-doc/<target>-doc/` 只放目标相关代码文档和方案附件，不再复制一套完整开发体系。

## 5. 创建步骤

### 5.1 root_default：创建项目默认开发体系

项目创建流程必须调用本步骤。

创建目录：

1. `dev/`
2. `dev/test/`
3. `dev/tmp/`
4. `dev-doc/`

创建文件：

1. `dev-doc/目录导读.md`
2. `dev-doc/编码规范.md`
3. `dev-doc/开发审计规范.md`
4. `dev-doc/开发事项总纲.md`
5. `dev-doc/开发事项计划.md`
6. `dev-doc/开发执行日志.md`
7. `dev-doc/开发审计报告.md`
8. `dev-doc/开发问题记录.md`

root_default 模式不得提前创建 `dev/<target>-dev/` 或 `dev-doc/<target>-doc/`。

### 5.2 target_workspace：创建目标开发工作区

创建：

1. `dev/<target>-dev/`
2. `dev/<target>-dev/test/`
3. `dev/<target>-dev/tmp/`
4. `dev-doc/<target>-doc/`
5. `dev-doc/<target>-doc/目录导读.md`
6. `dev-doc/<target>-doc/开发工作区说明.md`

不要把代码直接放在 `dev/` 根目录。

默认不创建空的 `开发方案/`。重型开发发生时，再创建 `dev-doc/<target>-doc/开发方案/<CODE-DESIGN-ID>.md`。

target_workspace 模式不得创建第二套 `编码规范.md`、`开发审计规范.md`、`开发事项总纲.md`、`开发事项计划.md`、`开发执行日志.md`、`开发审计报告.md`、`开发问题记录.md`。这些正式账本只存在于 `dev-doc/` 根目录。

### 5.3 创建目标工作区说明

target_workspace 模式创建 `dev-doc/<target>-doc/目录导读.md` 和 `dev-doc/<target>-doc/开发工作区说明.md`。初始内容可以很短：

```text
# 开发工作区说明

创建人员：<填写>
文件职责：记录本目标开发工作区的代码入口、测试入口、所属事项、方案附件和根级开发账本回写位置。
管理规范/模板：common/dev-doc/开发环境创建指南.md；dev-doc/编码规范.md；dev-doc/开发审计规范.md
引用文件：../开发事项总纲.md；../开发事项计划.md；../开发执行日志.md；../开发问题记录.md；审计报告入口按目标体系查看项目配置清单
记录方式：目标开发工作区说明；代码入口、测试入口或关联事项变化时更新。

## 1. 基本口径

本目录不是独立开发体系，只是目标代码文档区。

正式开发事项的总纲、计划、执行日志和问题记录登记到 dev-doc/ 根级开发账本；审计报告入口按目标体系查看项目配置清单。

## 2. 目录映射

| 路径 | 作用 |
|---|---|
| dev/<target>-dev/ | 代码目录 |
| dev/<target>-dev/test/ | 测试目录 |
| dev-doc/<target>-doc/开发方案/ | 重型开发方案附件目录，按需创建 |
```

### 5.4 创建账本文档

按 `编码规范.md` 和对应账本文档职责创建：

1. `开发事项总纲.md`
2. `开发事项计划.md`
3. `开发执行日志.md`
4. `开发审计报告.md`
5. `开发问题记录.md`

这些文件默认都是 append-only 滚动账本，最新记录追加到末尾。默认环境不创建空的 `编码方案.md`。发生重型开发时，再按事项创建具体方案文件，例如 `dev-doc/开发方案/<CODE-DESIGN-ID>.md` 或 `dev-doc/<target>-doc/开发方案/<CODE-DESIGN-ID>.md`；写作要求以 `编码规范.md` 为准，写法可参考 `编码方案范本.md`。

### 5.5 创建目录导读

`目录导读.md` 至少包含：

1. 当前目标体系是什么。
2. 代码目录。
3. 测试目录。
4. 开发文档入口。
5. 当前开发事项列表。
6. 审计报告入口，必须按目标体系写清是 `dev-doc/开发审计报告.md`、`exp-doc/实验审计报告.md` 还是 `ana-doc/案例审计报告.md`。
7. 问题记录入口。

### 5.6 登记到项目配置清单

在项目根目录 `项目配置清单.md` 记录：

1. 目标开发目录。
2. 开发 AI。
3. 开发审核员。
4. 写权限范围。
5. 核心文档入口。
6. 审计报告入口。

开发 AI 的写权限应绑定到对应 `dev/<target>-dev/`、`dev/<target>-dev/test/`、`dev-doc/<target>-doc/`，不默认拥有全部开发子目录。

## 6. 开发流程

### 6.1 轻量开发

适用于小脚本、局部工具、简单修复。

流程：

```text
确认目标和输入输出
-> 记录开发事项计划
-> 编码
-> 自测
-> 自检需求/目标是否一致
-> 记录开发执行日志
-> 必要时开发审核
```

轻量开发可以不写完整编码方案，但不能跳过输入输出说明、自测和执行日志。

### 6.2 重型开发

适用于多模块、长流程、公共模块、正式产物、重跑缓存、性能风险或失败代价高的开发。

流程：

```text
记录开发事项总纲
-> 记录开发事项计划
-> 编写编码方案
-> 方案审计通过
-> 编码实现
-> 测试和自检
-> 记录开发执行日志
-> 实现审计和测试验收
-> 问题修复和复审
-> 结论回写
```

方案审计未通过时，不应进入编码实现。

## 7. 体系创建校验方案

开发体系创建完成后，项目管理员或开发审核员必须做一次轻量校验。这个校验只证明“环境能承接开发事项”，不要求写真实业务代码，也不要求跑重型测试。

### 7.1 root_default 校验

项目创建时默认启用开发体系，必须校验：

1. `dev/`、`dev/test/`、`dev/tmp/`、`dev-doc/` 都存在。
2. `dev-doc/目录导读.md`、`dev-doc/编码规范.md`、`dev-doc/开发审计规范.md`、`dev-doc/开发事项总纲.md`、`dev-doc/开发事项计划.md`、`dev-doc/开发执行日志.md`、`dev-doc/开发审计报告.md`、`dev-doc/开发问题记录.md` 都存在。
3. 不存在空的 `dev-doc/编码方案.md`。
4. 不存在提前创建的 `dev/<target>-dev/`、`dev-doc/<target>-doc/` 目标开发工作区。
5. 本地 `编码规范.md` 和 `开发审计规范.md` 明确引用 common 对应规范，并说明不得削弱 common 硬约束。
6. `目录导读.md` 能说明代码目录、测试目录、开发文档入口、审计入口和重型方案创建口径。
7. 每个正式文档都有：创建人员、文件职责、管理规范/模板、引用文件、记录方式。
8. 不存在从其他项目复制来的业务代码、旧结果包、旧路径或旧业务结论。

### 7.2 target_workspace 校验

创建具体目标开发工作区时，必须校验：

1. `dev/<target>-dev/`、`dev/<target>-dev/test/`、`dev/<target>-dev/tmp/`、`dev-doc/<target>-doc/` 都存在。
2. `dev-doc/<target>-doc/目录导读.md`、`dev-doc/<target>-doc/开发工作区说明.md` 都存在。
3. 不存在 `dev-doc/<target>-doc/编码规范.md`、`开发审计规范.md`、`开发事项总纲.md`、`开发事项计划.md`、`开发执行日志.md`、`开发审计报告.md`、`开发问题记录.md` 这类第二套开发体系账本。
4. 不存在空的 `dev-doc/<target>-doc/编码方案.md`。
5. `dev-doc/<target>-doc/开发方案/` 只在已有重型开发事项并需要具体编码方案时创建；轻量开发或空工作区不创建。
6. 目标开发工作区已登记到项目配置清单，包括开发 AI、开发审核员、写权限范围和文档入口。
7. 目标开发工作区已登记正确审计报告入口：实验开发为 `exp-doc/实验审计报告.md`，案例分析开发为 `ana-doc/案例审计报告.md`，需求开发或项目工具开发为 `dev-doc/开发审计报告.md`。
8. 目标工作区没有把代码直接堆在 `dev/` 根目录。
9. 目标工作区事项已回写到对应开发账本和审计报告入口。

### 7.3 证据链 dry-run 校验

用一个不代表真实业务代码的测试事项，例如 `DEV-SMOKE-001`，做证据链 dry-run。可以只写最小记录，不需要生成真实代码。

最小链路应能串起来：

```text
开发事项总纲：记录 DEV-SMOKE-001 的来源、目标、边界
-> 开发事项计划：记录 DEV-PLAN-SMOKE-001 的步骤、输入输出和验收方式
-> 开发执行日志：记录 DEV-LOG-SMOKE-001 的关键步骤和产物位置；如无代码，明确 dry-run
-> 对应审计报告入口：记录 DEV-AUDIT-SMOKE-001 的初始化 / dry-run 审计结论
-> 开发问题记录：仅在存在非审计来源问题或需要审计问题索引时使用
```

通过标准：

1. 各文档之间的 ID 能互相引用。
2. 人或 AI 能从开发事项总纲一路追到计划、执行日志和对应审计报告入口。
3. 如果没有真实代码，执行日志要明确写“dry-run，无真实代码产物”。
4. 审计问题主记录写在对应审计报告入口；开发问题记录不被误用成审计问题主账。

### 7.4 校验结果记录

校验结论写入对应审计报告入口的初始化审计记录。

如果发现问题：

1. 审核员发现的问题，主记录写入对应审计报告入口。
2. 非审计人员发现的问题，写入 `开发问题记录.md`。
3. 如果问题会影响后续开发执行，必须先修复并复审，再允许正式开发事项开始。

## 8. 完成标准

开发工作区可用的最低标准：

1. 代码目录存在。
2. 测试目录存在。
3. 开发文档目录存在。
4. 本地 `编码规范.md` 存在并引用 common 规范。
5. 本地 `开发审计规范.md` 存在并引用 common 审计规范。
6. 总纲、计划、执行日志、审计报告、问题记录存在。
7. 目录导读能让人找到代码、测试、重型方案创建口径、日志、审计和问题。
8. 项目配置清单记录了开发目录和角色权限。
9. 体系创建校验通过。

## 9. 禁止事项

禁止：

1. 把所有代码直接放在 `dev/` 根目录。
2. 把需求文档放进 `dev-doc/<target>-doc/`。
3. 把编码方案当成需求文档。
4. 方案未审就做重型实现。
5. 审核员改业务代码或测试代码。
6. 为轻量脚本强制套完整重流程。
7. 把其他项目路径、样本、结论复制进本项目开发文档。

## 10. 创建后交付

创建完成后，应向项目管理员汇报：

1. 目标开发体系。
2. 代码目录。
3. 测试目录。
4. 开发文档目录。
5. 已创建文档。
6. 角色和权限登记位置。
7. 是否可开始开发事项。