# 项目环境创建指南

创建人员：Codex  
文件职责：指导项目管理员按通用项目体系创建新项目、初始化基础文档、角色权限和可选体系。  
管理规范/模板：../../全局规范.md；本目录项目规范.md。  
引用文件：项目总览范本.md；项目规范模版.md；项目配置清单模版.md；项目事项总纲模版.md；项目事项计划模版.md；项目执行日志模版.md；项目事项审计报告模版.md；项目问题记录模版.md；项目变更记录模版.md；../ai-workplace/AI工作空间创建指南.md。  
记录方式：创建指南；项目创建流程变化时更新。

## 1. 使用场景

当项目管理员要创建一个新项目时，按本指南执行。

本指南只负责项目体系初始化，不替代需求、编码、实验、数据、案例分析等具体体系的创建指南。

## 2. 输入

创建项目前应明确：

1. 项目名称。
2. 项目 ID 或稳定目录名。
3. 项目根目录。
4. 项目目标。
5. 项目介绍和背景。
6. 预计时间周期或当前阶段。
7. 项目管理员。
8. 初始 AI 名单。
9. 初始角色分配。
10. 初始启用体系。
11. 是否需要 git 仓库。

如果用户没有提供项目名称、项目根目录、项目目标、项目背景、时间周期或项目管理员，创建者必须先主动询问；不得用“待补”创建一个不可用的项目总览。  
如果用户明确允许先建空项目，可以把缺失项标为“用户允许待补”，但必须在 `项目事项计划.md` 和 `项目问题记录.md` 中登记待补事项，并在项目审计中标记为未完全可用。

## 3. 创建步骤

### 3.1 创建项目根目录

在 `manage_system` 下创建项目目录。

项目目录名应简短、稳定、可读。

### 3.2 创建项目基础文档

用本目录模板创建：

1. `项目总览.md`（由 `项目总览范本.md` 创建，记录项目稳定基础信息、目标、周期、背景和关键入口）
2. `项目规范.md`（项目根目录的本地项目规范，由 `项目规范模版.md` 创建）
3. `项目配置清单.md`（由 `项目配置清单模版.md` 创建，记录体系、角色、权限和目录配置）
4. `项目事项总纲.md`
5. `项目事项计划.md`
6. `项目执行日志.md`
7. `项目事项审计报告.md`
8. `项目问题记录.md`
9. `项目变更记录.md`

这些文档都放在项目根目录。

模板中的相对路径按“复制到项目根目录后的文件位置”计算。不要把 `common/project-doc` 下模板文件自身的位置当成项目正式路径。

`项目总览.md` 是项目稳定画像，记录项目名、创建时间、目标、周期、背景、范围、关键来源和文档入口。  
项目根目录 `项目规范.md` 默认可以很短：引用 `common/project-doc/项目规范.md`，记录项目边界、项目配置入口、项目总览入口和本地补充即可。启用体系、目录映射、角色和权限写入 `项目配置清单.md`。

项目初始化本身也是项目事项。创建基础文档后，必须在 `项目事项总纲.md` 和 `项目事项计划.md` 中记录初始化事项、来源聊天记录、计划目标、执行步骤和验收方式。

初始化阶段因为基础文档需要先被创建，允许在同一轮中补齐计划审计和执行审计，但必须在 `项目事项审计报告.md` 中分开记录：

1. 初始化计划审计：检查创建计划是否按本指南覆盖基础文档、基础目录、项目配置清单、执行日志和审计。
2. 初始化执行审计：检查实际创建结果是否符合计划和完成标准。

### 3.3 创建项目基础目录

默认创建：

```text
dev/
dev-doc/
tmp/
```

必须为 `项目配置清单.md` 中登记的每个 AI 创建工作空间目录，例如：

```text
ai-<AI_NAME>/
```

AI 工作空间目录必须统一使用 `ai-<name>/` 命名，`<name>` 使用稳定英文名或拼音小写，例如 `ai-andrew/`、`ai-codex/`。不得创建裸 AI 名目录。

创建或新增 AI 工作空间时，必须按 `../ai-workplace/AI工作空间创建指南.md` 执行：创建 `ai-<name>/tmp/`、`ai-<name>/draft/`、`ai-<name>/worklog/`、`ai-<name>/工作说明.md`、`ai-<name>/项目问题反馈.md`，其中 `项目问题反馈.md` 写法参考 `../ai-workplace/项目问题反馈范本.md`；并同步更新 `项目配置清单.md`、项目执行日志和项目变更记录。

如果创建时暂时没有除项目管理员外的 AI，也至少要为项目管理员创建工作空间；后续新增 AI 时，也按 `../ai-workplace/AI工作空间创建指南.md` 执行。

项目创建时必须调用 `common/dev-doc/开发环境创建指南.md` 的 `root_default` 模式创建默认开发体系。该模式会创建 `dev/`、`dev/test/`、`dev/tmp/`、`dev-doc/` 以及 `dev-doc/` 下的开发根级账本文档。

项目创建阶段不得提前创建未启用目标体系的 `dev/<target>-dev/`、`dev-doc/<target>-doc/` 完整工作区。具体目标开发工作区仍按 `common/dev-doc/开发环境创建指南.md` 的 `target_workspace` 模式创建。

目标开发工作区只创建目标代码目录、测试目录、目标代码文档区入口和工作区说明。不得在 `dev-doc/<target>-doc/` 下复制第二套 `编码规范.md`、`开发审计规范.md`、开发事项总纲、开发事项计划、开发执行日志、开发审计报告或开发问题记录。正式开发总纲、计划、执行日志和问题记录只在 `dev-doc/` 根目录；审计报告入口按目标体系填写，实验开发写 `exp-doc/实验审计报告.md`，案例分析开发写 `ana-doc/案例审计报告.md`。

### 3.4 启用体系

项目管理员按需要启用体系。

常见体系：

1. 需求体系：`pro-doc/`
2. 开发体系：项目创建时按 `common/dev-doc/开发环境创建指南.md` 的 `root_default` 模式默认创建；具体目标开发工作区按该指南的 `target_workspace` 模式创建，例如 `dev/pro-dev/`、`dev-doc/pro-doc/`，但目标文档区只放目标代码文档和方案附件
3. 实验体系：`exp-doc/`、`exp-data/`
4. 案例分析体系：`ana-doc/`、`ana-data/`
5. 数据体系：`data-doc/`、项目约定的数据目录

启用体系时，按该体系自己的环境创建指南初始化目录和本地规范。

### 3.5 更新项目配置清单

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

1. 已启用体系。
2. 目录映射。
3. AI 角色和权限。
4. AI 工作空间。
5. 核心文档入口。

不要把体系规范正文复制到项目配置清单里。

### 3.6 更新项目规范

在 `项目规范.md` 中记录：

1. 项目边界。
2. 项目配置入口：`项目配置清单.md`。
3. 项目总览入口：`项目总览.md`。
4. 项目本地特殊补充。

不要把体系配置、AI 名单、权限清单复制到项目规范里。

### 3.7 记录执行日志

在 `项目执行日志.md` 追加初始化记录：

1. 创建时间。
2. 创建人员。
3. 创建了哪些目录。
4. 创建了哪些文档。
5. 启用了哪些体系。
6. 分配了哪些角色。
7. 还有哪些待补项。

### 3.8 项目级审计

创建完成后，项目审核员或项目管理员做一次初始化审计。

审计结果写入 `项目事项审计报告.md`。

初始化审计必须至少包含计划审计和执行审计两条记录；如果计划审计或执行审计不通过，项目环境不得标记为可用。

初始化执行审计必须显式检查开发体系默认规则：

1. `dev/`、`dev-doc/` 根目录已创建。
2. `dev/test/`、`dev/tmp/` 已创建。
3. `dev-doc/目录导读.md`、`dev-doc/编码规范.md`、`dev-doc/开发审计规范.md`、`dev-doc/开发事项总纲.md`、`dev-doc/开发事项计划.md`、`dev-doc/开发执行日志.md`、`dev-doc/开发审计报告.md`、`dev-doc/开发问题记录.md` 已创建。
4. `项目配置清单.md` 已登记开发体系。
5. 未提前创建 `dev/<target>-dev/`、`dev-doc/<target>-doc/` 等目标开发工作区。
6. 后续目标开发工作区创建入口指向 `common/dev-doc/开发环境创建指南.md`。
7. 后续目标开发工作区不得复制第二套开发账本；创建后必须执行 `common/dev-doc/开发环境创建指南.md` 的 target_workspace 校验。

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

项目体系创建完成后，项目管理员或项目审核员必须做一次轻量校验。这个校验只证明“项目环境能承接事项管理和后续体系启用”，不要求创建未启用体系，也不要求跑真实业务事项。

### 4.1 基础目录和文档校验

检查：

1. 项目根目录存在。
2. `项目总览.md`、`项目规范.md`、`项目配置清单.md`、`项目事项总纲.md`、`项目事项计划.md`、`项目执行日志.md`、`项目事项审计报告.md`、`项目问题记录.md`、`项目变更记录.md` 都存在。
3. 每个正式文档都有：创建人员、文件职责、管理规范/模板、引用文件、记录方式。
4. `项目总览.md` 已记录项目名称、项目 ID、项目根目录、创建时间、项目目标、时间周期、背景和项目管理员。
5. `项目规范.md` 只引用 common 项目规范，不复制 common 正文。
6. 不存在从其他项目复制来的旧路径、旧业务内容、旧事项结论或旧角色配置。

### 4.2 配置和权限校验

检查：

1. `项目配置清单.md` 已登记项目管理员、初始 AI、角色、权限、工作空间和启用体系。
2. `项目配置清单.md` 中登记的 AI 工作空间都已创建。
3. 每个已登记 AI 的 `工作说明.md` 和 `项目问题反馈.md` 已创建，且 `工作说明.md` 中的角色、权限与 `项目配置清单.md` 一致，`项目问题反馈.md` 已说明参考 `common/ai-workplace/项目问题反馈范本.md`。
4. 已启用体系的目录和本地规范存在；未启用体系没有被提前创建大量空目录。
5. 项目执行日志记录了初始化动作。
6. 如项目配置、角色、权限或目录在初始化中发生变化，项目变更记录已登记。

### 4.3 默认开发体系校验

项目创建默认调用开发体系 `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. 后续目标开发工作区创建入口指向 `common/dev-doc/开发环境创建指南.md`。

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

项目初始化本身就是一个项目事项，最小链路必须能串起来：

```text
项目总览：记录项目稳定基础信息、背景、目标、周期和关键入口
-> 项目事项总纲：记录 PROJECT-INIT 的来源、目标、边界
-> 项目事项计划：记录 PLAN-PROJECT-INIT 的创建步骤和验收方式
-> 项目执行日志：记录 LOG-PROJECT-INIT 的创建动作、目录和文档
-> 项目事项审计报告：记录 AUDIT-PROJECT-PLAN-INIT / AUDIT-PROJECT-EXEC-INIT 的审计结论
-> 项目问题记录：仅在存在非审计来源问题或需要审计问题索引时使用
-> 项目变更记录：记录项目目录、配置、角色或体系启用变化
```

通过标准：

1. 各文档之间的 ID 能互相引用。
2. 人或 AI 能从项目事项总纲一路追到计划、执行日志、审计报告和变更记录。
3. 审计问题主记录写在项目事项审计报告；项目问题记录不被误用成审计问题主账。
4. 初始化计划审计和执行审计都通过。

### 4.5 校验结果记录

校验结论写入 `项目事项审计报告.md` 的初始化审计记录。

如果发现问题：

1. 审核员发现的问题，主记录写入 `项目事项审计报告.md`。
2. 非审计人员发现的问题，写入 `项目问题记录.md`。
3. 如果问题会影响后续事项管理或体系启用，必须先修复并复审，再允许项目环境标记为可用。

## 5. 完成标准

项目环境可用的最低标准：

1. 项目根目录存在。
2. 项目基础文档齐全，包含 `项目总览.md`。
3. 项目规范没有复制 common 正文。
4. 项目配置清单能解释启用体系、AI、角色、权限、目录和工作空间。
5. 项目配置清单中登记的 AI 工作空间已创建，且每个工作空间都有 `工作说明.md` 和 `项目问题反馈.md`。
6. 已启用体系的本地规范存在；开发体系根目录必须按 `common/dev-doc/开发环境创建指南.md` 的 `root_default` 模式创建完整根级账本，目标开发工作区创建后再要求目标级本地开发规范。
7. 开发体系默认根目录已创建，且未提前创建目标开发工作区。
8. 项目执行日志记录了初始化过程。
9. 项目事项审计报告记录了初始化审核。
10. 体系创建校验通过。

## 6. 禁止事项

禁止：

1. 未经项目管理员确认就启用体系。
2. 把其他项目文档、路径、业务内容复制进新项目。
3. 把 common 规范全文复制到项目规范。
4. 创建大量未启用体系目录。
5. 只建目录不建入口文档。
6. 只在聊天里说明项目背景，不写入 `项目总览.md` 和项目事项总纲。

## 7. 创建后交付

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

1. 项目根目录。
2. 已创建文档。
3. 已创建目录。
4. 已启用体系。
5. AI 工作空间。
6. 审计结论。
7. 待补事项。