edit | blame | history | raw

开发环境创建指南

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

1. 使用场景

本指南有两个使用场景：

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

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

项目创建时默认创建：
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 项目默认开发体系根目录

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

3.2 目标开发工作区

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

示例：

需求开发：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。初始内容可以很短：

# 开发工作区说明

创建人员：<填写>
文件职责：记录本目标开发工作区的代码入口、测试入口、所属事项、方案附件和根级开发账本回写位置。
管理规范/模板：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 轻量开发

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

流程：

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

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

6.2 重型开发

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

流程：

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

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

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。可以只写最小记录，不需要生成真实代码。

最小链路应能串起来：

开发事项总纲：记录 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. 是否可开始开发事项。