项目规范

创建人员：Codex
文件职责：定义所有项目通用的项目管理规范、核心流程、关键文档、项目管理员职责和项目级审计闭环。
管理规范/模板：../../全局规范.md；../../体系说明.md；本文件是 common 下的全局项目规范，不是项目本地规范模板。
引用文件：../../管理系统说明.md；../../全局规范.md；../../体系说明.md；项目环境创建指南.md；项目规范模版.md；项目配置清单模版.md。
记录方式：全局项目规范文档；项目管理规则变更时更新本文件，并同步目录导读。

1. 定位

本文件是 common/project-doc/项目规范.md，是所有项目默认遵守的全局项目规范。

项目根目录中的 项目规范.md 是本地项目规范，默认引用本文件，只记录本项目目标、边界、项目配置入口和项目特化补充，不复制本文件正文。

项目根目录中的 项目配置清单.md 是当前项目配置事实源，统一记录启用体系、目录映射、AI 角色、权限边界、工作空间和核心文档入口。

项目体系是一种基础体系，负责创建和治理一个项目本身。

它回答：

1. 这个项目为什么存在。
2. 项目目标和边界是什么。
3. 项目稳定基础信息在哪里。
4. 项目配置清单在哪里。
5. 项目启用了哪些体系插件。
6. 项目有哪些角色和 AI。
7. 每个体系的目录在哪里。
8. 项目事项总纲、项目事项计划、日志、审计和问题如何记录。

项目体系不替代具体业务体系。需求、编码、实验、案例分析、数据等体系仍按各自 common 规范和项目本地规范执行。

2. 核心原则

项目体系遵守以下原则：

1. 一个项目一个项目根目录。
2. 一个项目必须有 项目总览.md。
3. 一个项目必须有 项目规范.md。
4. 一个项目必须有 项目配置清单.md。
5. 项目管理员决定启用哪些体系。
6. 未启用的体系不产生执行义务。
7. 启用体系后，必须创建对应目录和本地体系规范。
8. 项目总览记录稳定项目信息，项目配置清单记录当前动态配置，项目事项总纲记录滚动事项，不互相替代。
9. 项目规范只记录项目特化内容，不重复抄写全局规范和体系规范。
10. 项目级管理动作必须有日志和审计入口。
11. 项目内具体事项必须能追到项目目标和启用体系。
12. 当 mb-ms-doc 作为工作区管理根目录时，工作区内的业务子项目目录应以 project- 开头；每个业务子项目应拥有独立 Git 仓库，不加入 mb-ms-doc 仓库管理。

2.1 业务子项目目录与 Git 边界

mb-ms-doc 仓库保存全局规范、体系模板、公共文档和管理根目录规则，不直接管理具体业务子项目的版本历史。

工作区内的业务子项目按以下口径管理：

1. 业务子项目目录建议统一使用 project-<name> 命名，便于管理根目录 .gitignore 排除和人工识别。
2. 每个业务子项目应在自身项目根目录内初始化独立 Git 仓库。
3. 业务子项目不得作为普通文件加入 mb-ms-doc 仓库提交。
4. mb-ms-doc 根仓库应排除 project-* 业务子项目目录。
5. 如果历史项目、示例项目或特殊项目暂时不满足 project-* 命名，应在项目总览、项目配置清单或项目变更记录中说明原因和 Git 管理边界。
6. 项目管理员创建新项目时，应同步确认项目目录名、独立 Git 仓库、远端地址、提交身份和管理根目录排除规则。

3. 核心流程

3.0 本地项目流程优先级

common 项目规范规定项目治理底线和默认流程，项目根目录 项目规范.md 可以设计本项目自己的项目管理流程。

本地项目流程设计必须满足项目体系硬约束：项目目标和边界清楚、来源聊天记录可追踪、事项计划先审计、执行关键节点有日志、执行结束有审计、项目级变更有记录、结论回写到账本。

本地流程可以做两类调整：

1. 新增流程：例如新增项目专用审批流程、交付验收流程、跨 AI 协作流程。
2. 修改默认流程：例如把项目事项生命周期拆分、合并、替换为本项目更适合的流程。

如果只是新增流程，只要不违反项目体系硬约束即可放行。
如果是修改默认流程，必须在项目根目录 项目规范.md、项目事项计划.md 或对应体系规范中写清楚覆盖范围、替换原因、输入输出、关键证据链和审计点。

本地项目流程一旦设计完成并通过审计，执行时以本地流程为准；项目审核员也应按已通过的本地流程审计执行结果。只有发现本地流程违反项目体系硬约束时，才回到 common 项目规范要求整改。

3.1 项目初始化流程

项目发起
-> 创建项目目录
-> 创建项目总览.md
-> 创建项目规范.md
-> 创建 项目配置清单.md
-> 创建项目事项总纲 / 项目事项计划 / 项目执行日志
-> 项目管理员决定启用体系
-> 初始化对应体系目录和本地规范
-> 分配 AI 角色和工作空间
-> 执行项目事项
-> 项目级审计
-> 问题修复 / 变更记录 / 复审

3.2 项目事项生命周期流程

项目事项是项目级管理事项，不替代需求、编码、实验、案例分析等体系内部事项。

项目事项默认按以下流程推进：

事项来源 / 聊天要求 / 上游文档
-> 写入项目事项总纲，说明背景、目标、边界、当前状态
-> 拆分到项目事项计划，明确负责人、步骤、输入、输出、验收方式
-> 判断事项风险与复杂度
-> 普通、可逆、项目内事项直接执行；实质高风险或复杂事项才做计划审计
-> 执行事项
-> 在项目执行日志记录关键节点、关键输入、关键输出、偏离和当前状态
-> 必要时写项目变更记录
-> 普通事项由请求者或安排者验收；实质阶段门才做独立执行审计
-> 如审计发现问题，主记录写项目事项审计报告；如非审计人员发现问题，主记录写项目问题记录
-> 同一轮问题一次给全，合并修复后做一次必要复审
-> 结论回写到项目事项总纲和项目事项计划
-> 事项完成 / 暂停 / 取消

关键要求：

1. 项目事项开始前，必须能在项目事项总纲中找到背景、目标和关键来源聊天记录或上游路径。
2. 项目事项执行前，必须能在项目事项计划中找到拆分步骤、输入输出、验收方式和来源聊天记录。
3. 普通、可逆、项目内 L0/L1 事项不要求实施前独立计划审计；涉及权限扩张、不可逆外部写入、凭据、破坏性数据操作、正式发布、跨项目/跨控制面或重大结论的事项，才要求在执行前通过相应独立审核。
4. 项目事项执行中，关键节点必须写入项目执行日志。
5. 普通事项完成后由请求者或安排者做功能/结果验收即可；需要独立审核的事项，审核应集中在实质阶段门，不做逐动作、逐文件或逐尝试复核。
6. 如果事项改变了项目目标、边界、角色、目录、体系启用状态或关键规范，必须同时进入项目变更流程。
7. 同一已登记事项内的普通修复和重跑不要求新建逐次 A001；确需授权时，优先使用项目级事项、时间窗或阶段范围合同。

3.3 项目变更流程

项目变更记录只记录会改变项目治理结构、项目边界或后续执行方式的变化。

以下情况必须写入 项目变更记录.md：

1. 启用或停用体系。
2. 新增、删除、移动或重命名项目级正式目录。
3. 调整 AI 角色、权限边界、审核员身份或工作空间。
4. 修改项目目标、项目边界、阶段优先级或交付范围。
5. 修改项目根目录 项目规范.md 或 项目配置清单.md 的关键规则。
6. 修改项目级证据链入口、正式账本入口或审计入口。
7. 因审计问题导致项目级流程、目录或权限需要调整。

以下情况通常不需要写项目变更记录：

1. 普通执行日志新增一条记录。
2. 具体体系内部的需求、代码、实验、案例分析日常迭代。
3. 临时草稿、临时文件或一次性分析结果。
4. 不改变项目治理结构的文档措辞修订。

项目变更默认按以下流程：

发现变更需求
-> 判断是否属于项目级变更
-> 在项目事项计划或项目执行日志中记录变更动作
-> 执行变更
-> 写入项目变更记录，说明变更前、变更后、原因和影响范围
-> 同步更新项目规范、项目配置清单、目录导读或相关入口
-> 项目级审计
-> 如不通过，主记录写项目事项审计报告；需要跨轮跟踪时在项目问题记录建索引，并修复 / 回滚 / 复审

紧急变更可以先做最小必要动作，但必须在同一轮事项内补齐项目执行日志和项目变更记录。

3.4 体系启用 / 停用流程

启用体系：

项目管理员决定启用体系
-> 在项目配置清单.md 登记体系、目录、common 规范、本地规范和适用角色
-> 创建体系目录和本地规范
-> 在项目配置清单.md 分配角色和工作空间
-> 写项目执行日志
-> 写项目变更记录
-> 项目级审计

停用体系：

确认停用原因
-> 在项目变更记录中记录停用原因和影响范围
-> 在项目配置清单.md 标记停用
-> 保留历史产物入口
-> 写项目执行日志
-> 项目级审计

3.5 项目级问题闭环流程

项目级问题按以下流程处理：

非审计人员发现项目级问题
-> 写入项目问题记录
-> 判断是否需要项目变更
-> 制定修复动作并写入项目事项计划或项目执行日志
-> 执行修复
-> 复审

审计人员发现的项目级问题，主记录写入项目事项审计报告；如果需要长期跟踪，再在项目问题记录中建立索引。

审计中发现项目级问题
-> 写入项目事项审计报告
-> 如需跨轮跟踪，写入项目问题记录索引
-> 判断是否需要项目变更
-> 制定修复动作并写入项目事项计划或项目执行日志
-> 执行修复
-> 复审
-> 关闭问题并回写项目事项总纲 / 计划 / 变更记录

项目级问题只记录项目治理问题。具体需求、代码、实验、案例分析问题，优先记录到对应体系的问题文档；如果这些问题影响项目级目录、权限、目标或体系启用，再同步登记项目级问题或变更。

3.6 AI 工作空间问题反馈与反复返修升级

每个 AI 工作空间中的 项目问题反馈.md 是该 AI 向项目管理员反馈重大协作问题的私有入口。

它服务于项目治理，不替代正式审计报告、项目问题记录、体系问题记录或执行日志。

适合写入：

1. 角色权限、工作空间、体系入口、流程边界不清，已经影响项目或体系推进。
2. 同一事项或同类问题多轮返修后仍重复出现，通常大于等于 3 次。
3. 审核员判断需要项目管理员介入协调、收口口径、调整角色、调整流程或暂停扩展。
4. AI 首次阅读工作说明、项目配置清单或体系规范后，发现职责/权限/入口存在影响执行的重大不清楚。

审核员发现被审事项存在问题时，仍必须先把正式审计结论写入对应审计报告。
如果同一问题经过多轮返修仍重复出现，审核员应额外在自己工作空间的 项目问题反馈.md 追加一条反复返修问题反馈。

反复返修问题反馈必须尽量记录清楚：

1. 关联事项 ID。
2. 关联计划 ID 或设计 ID。
3. 关联执行日志 ID。
4. 关联审计报告 ID。
5. 问题发生步骤。
6. 反复次数。
7. 已要求修复内容。
8. 为什么判断为反复问题。
9. 影响范围。
10. 关联证据路径。
11. 建议项目管理员介入方式。
12. 修复建议。该字段必填，至少给出下一步应怎么收敛。
13. 是否需要完整方案。如果问题复杂、反复难修或涉及多模块/多流程，应标记为“是”。
14. 完整方案路径。需要完整方案时填写，例如代码修复方案、流程整改方案或专项收敛方案路径。
15. 方案摘要。需要完整方案时，摘要说明方案核心动作、责任边界和验收方式。

项目问题反馈.md 的写法参考 common/ai-workplace/项目问题反馈范本.md，但不要求逐字复制范本。项目文件只要保留关键字段、记录边界和 append 写法即可。

4. 核心文档

4.1 项目总览.md

项目总览.md 是项目稳定画像入口。

它记录：

1. 项目名称、项目 ID、项目根目录、创建时间和项目管理员。
2. 项目一句话介绍。
3. 项目背景和关键来源聊天记录摘要。
4. 项目目标、阶段目标和完成标准。
5. 项目时间周期、当前阶段和里程碑。
6. 项目范围、边界、关键假设和风险。
7. 核心文档入口。

项目总览不维护动态 AI 名单、权限、目录映射和体系启停事实；这些以 项目配置清单.md 为准。

4.2 项目根目录 项目规范.md

项目根目录 项目规范.md 是项目治理入口。

它记录：

1. 项目名称。
2. 项目目标。
3. 项目边界。
4. 项目管理员。
5. 项目配置入口。
6. 项目本地特殊补充。
7. 与全局规范冲突时的处理方式。

项目规范不复制全局规范和 common 体系规范正文。

4.3 项目配置清单.md

项目配置清单.md 记录当前项目的动态配置事实源。

它统一记录：

1. 已启用体系。
2. 各体系目录映射。
3. common 规范和本地规范入口。
4. 具体 AI 名单。
5. AI 角色、工作空间和权限边界。
6. 核心文档入口。

AI 名单、角色变化、工作空间调整、体系启停和目录映射变化，更新 项目配置清单.md，并同步写入项目变更记录和项目执行日志。

4.4 项目事项总纲.md

项目事项总纲记录项目事项背景、目标、阶段状态和项目级结论。

它是项目级事项总账本。

项目事项总纲是项目级滚动账本，不是单个事项的独立文件，也不替代 项目总览.md。项目内新增阶段、项目管理事项、体系启用事项时，默认追加到这一本账本。

4.5 项目事项计划.md

项目事项计划记录项目阶段、里程碑、体系启用计划和项目级任务。

它是项目事项计划账本。

项目事项计划也是项目级滚动账本，不按单个任务默认拆分文件。具体需求、编码、实验等体系内部计划，仍写入对应体系自己的计划或设计文档。

4.6 项目执行日志.md

项目执行日志记录项目创建、目录初始化、体系启用、角色分配、项目级变更和关键管理动作。

它不替代具体体系的执行日志。

4.7 项目事项审计报告.md

项目事项审计报告记录项目创建、体系启用、权限、目录、证据链、事项计划合理性和关键管理动作的审核结果。

项目事项审计报告只审项目治理事项，不替代各体系的专业审计报告。

4.8 项目问题记录.md

项目问题记录只记录项目级问题，例如：

1. 目录结构问题。
2. 角色权限问题。
3. 体系启用不完整。
4. 项目规范和 common 规范冲突。
5. 项目级证据链断裂。

具体需求、编码、实验、案例分析问题优先记录在对应体系的问题文档中，项目级问题记录只保留索引或项目治理问题。

项目审计人员发现的问题，主记录写在项目事项审计报告；项目问题记录只保留需要跨轮跟踪的索引或非审计来源问题。

4.9 项目变更记录.md

项目变更记录记录：

1. 启用或停用体系。
2. 目录调整。
3. 角色权限调整。
4. 项目目标或边界变化。
5. 项目规范重大修订。

5. 项目管理员职责

项目管理员负责：

1. 创建项目。
2. 维护项目规范。
3. 决定启用哪些体系。
4. 初始化体系目录。
5. 维护项目配置清单。
6. 创建 AI 工作空间。
7. 新增或调整 AI 时，按 common/ai-workplace/AI工作空间创建指南.md 创建工作空间、生成工作说明并更新项目配置清单。
8. 确保项目文档和目录入口可读。
9. 组织项目级审计。
10. 处理项目级问题闭环。

项目管理员不替代各体系的执行者和审核员。

6. 体系启用规则

启用一个体系时，必须：

1. 在 项目配置清单.md 中登记。
2. 创建该体系目录。
3. 创建该体系本地规范。
4. 创建必要的本地账本、日志、审计报告或问题记录。
5. 在 项目配置清单.md 中分配对应角色、权限和工作空间。
6. 在项目执行日志中记录启用动作。

开发体系是默认基础体系，启用规则按以下口径执行：

1. 项目创建时默认创建 dev/、dev-doc/ 根目录，并在 项目配置清单.md 登记开发体系。
2. 不提前创建所有目标开发工作区。
3. 只有实际创建 dev/<target>-dev/、dev-doc/<target>-doc/ 时，才创建目标代码目录、测试目录、目标代码文档区入口和 开发工作区说明.md。
4. 目标开发工作区不得实例化第二套本地 编码规范.md、开发审计规范.md、开发事项账本、执行日志、审计报告和问题记录。
5. 所有开发事项统一登记到 dev-doc/ 根级开发账本；目标开发工作区只保存目标相关代码文档和方案附件。
6. 目标开发工作区创建前后，开发事项都遵守 common/dev-doc 全局开发规范和项目根级 dev-doc/编码规范.md。

停用体系时，必须：

1. 在项目变更记录中记录原因。
2. 在项目配置清单中标记停用。
3. 保留历史产物入口，不得直接删除。

7. 项目审计边界

7.1 事项级整体审核原则

审核员审核事项时，必须以事项为基本单元，而不是以单个步骤、单个文件或单个输出为基本单元。

事项单元以对应体系总纲文档中的一个目标 / 事项条目为准。审核员应围绕该事项整体检查：

1. 目标是否清楚。
2. 设计 / 计划是否能支撑目标。
3. 执行日志是否覆盖关键节点。
4. 关键输入、关键输出、关键数据和关键产物是否可追踪。
5. 结论是否回写。
6. 问题是否闭环。

如果审核过程中发现关键节点、关键数据、关键产物或关键证据链缺失，应作为审计问题反馈。

审核员不得把不影响事项目标、结论、关键证据链或下游使用的边角料问题升级为阻断问题；不得通过拆分步骤审计的方式层层加码。

审核员应在一轮中返回完整的实质问题集合。除非修订引入新的实质风险，不得围绕同一边界连续制造单点 supplemental 审核、权限存在性审核或逐尝试审核。

在不同体系中，事项单元对应如下：

体系	审核事项单元
项目体系	项目事项总纲.md 中的一个项目事项
需求体系	需求总纲.md 中的一个需求目标或需求事项
开发体系	开发事项总纲.md 中的一个开发事项
实验体系	实验总纲.md 中的一个实验目标或实验事项
案例分析体系	案例总纲.md 中的一个案例目标或案例事项
数据体系	数据体系总纲或数据事项账本中的一个数据目标或数据事项

7.2 项目级审计边界

项目级审计重点看：

1. 项目是否有清晰目标和边界。
2. 项目是否只启用了需要的体系。
3. 启用体系是否创建了必要入口。
4. 项目规范是否没有重复抄写体系规范。
5. 项目配置清单是否能解释 AI、角色、权限、工作空间和启用体系。
6. 目录结构是否能让后续 AI 找到关键文档。
7. 项目级管理动作是否有日志。
8. 项目是否混入其他项目内容。
9. 项目事项计划是否合理，是否能满足项目目标。
10. 项目事项计划是否和来源聊天记录、上游文档一致。
11. 项目事项执行是否按已审计通过的计划进行。

项目级审计不负责替代需求审计、代码审计、实验审计或案例审计。

8. 完成标准

一个项目环境创建完成，至少满足：

1. 项目根目录存在。
2. 项目总览.md 存在，且记录项目名称、目标、周期、背景和项目管理员。
3. 项目规范.md 存在。
4. 项目配置清单.md 存在。
5. 项目事项总纲、项目事项计划、项目执行日志、项目事项审计报告、项目问题记录、项目变更记录存在。
6. 已启用体系的目录和本地规范存在；开发体系根目录可只登记 common 规范，目标开发工作区创建后才要求本地开发规范。
7. AI 工作空间存在。
8. 项目事项审计报告记录初始化审核结论。

一句话：项目体系负责把项目建起来、把体系装进去、把人和目录管清楚；具体业务怎么做，交给对应体系。