# 全局规范

创建人员：Codex  
文件职责：记录管理体系下所有项目、所有 AI、所有事项默认遵守的全局规则。  
管理规范/模板：参考 `管理系统说明.md` 和 `体系说明.md`；本文件是全局执行规则，不是体系说明书。  
引用文件：`管理系统说明.md`；`体系说明.md`；`体系创建流程.md`；`全局存储体系.md`；`全局数据格式.md`；`common/ai-workplace/AI工作空间创建指南.md`；`common/pro-doc/需求规范.md`；`common/dev-doc/编码规范.md`；`common/exp-doc/实验规范.md`；`common/exp-doc/实验审核规范.md`。  
记录方式：本文件为全局规则文档；新增规则默认追加到对应章节，重大口径变化必须保留变更说明，不得静默覆盖历史原因。

## 1. 文档定位

`全局规范.md` 是所有项目和所有 AI 的最高通用执行规则。

它负责规定：

1. 文件如何创建、修改、删除、引用。
2. 项目目录和体系目录如何管理。
3. AI 的角色、权限、工作空间和审计边界。
4. 事项如何记录背景、目标、过程、结果和审计。
5. 问题如何归因、记录、修复、复验。
6. 各体系如何作为可选插件启用。

`管理系统说明.md` 负责解释体系结构；`全局规范.md` 负责规定执行约束。两者冲突时，以 `全局规范.md` 为准，并同步修正说明文档。

## 2. 生效范围和优先级

本文件适用于：

1. `manage_system` 下所有项目。
2. 所有项目管理员、开发 AI、需求 AI、实验员、案例分析员、审核员和临时协作 AI。
3. 所有需求、编码、实验、案例分析、数据处理、审计和归档事项。

规范优先级：

```text
全局规范.md
-> common/<体系>/全局体系规范（项目体系为 common/project-doc/项目规范.md）
-> 项目根目录/项目规范.md
-> 项目本地体系规范
-> 具体需求 / 设计 / 实验 / 执行文档
```

项目管理员通过项目根目录 `项目配置清单.md` 决定启用哪些体系。一旦启用某个体系，该体系的 common 规范自动生效。

项目根目录 `项目规范.md` 只记录项目目标、边界、项目配置入口和项目特殊补充，不重复书写对应体系规范或全局规范已经规定的内容，避免多处重复后产生冲突。

项目本地规范可以补充项目特化规则，也可以在满足全局硬约束和 common 体系硬约束的前提下，设计本地事项流程。全局硬约束和 common 体系硬约束不能被削弱或冲突。

流程优先级按两阶段判断：

1. 流程设计阶段：本地流程必须说明新增或替换了什么、为什么替换、输入输出是什么、证据链怎么留、审核点在哪里，并通过对应审核。
2. 流程执行阶段：已通过审核的本地流程优先于 common 默认流程；只有发现本地流程违反全局或 common 硬约束时，才回到全局 / common 规范要求整改。

如果发生冲突：

1. 先按全局规范执行。
2. 将冲突记录为项目规范问题。
3. 修正本地项目规范或具体事项文档。
4. 冲突未解决前，不得把相关事项标记为完成。

## 3. 体系插件原则

`common/` 下的需求体系、开发体系、实验体系、数据体系、案例分析体系，都是体系插件。项目体系和开发体系是项目创建时默认自带的基础体系；其他体系由项目管理员按需启用。

默认口径：

1. `common/` 是全局能力库。
2. 项目创建时默认启用项目体系和开发体系。
3. 项目管理员决定是否额外启用需求、实验、案例分析、数据等体系。
4. 未启用的非默认体系，不对项目产生执行义务。
5. 启用某个体系后，项目必须创建对应目录、入口文档和本地规范。开发体系是例外：一个项目只有一套开发体系账本和本地开发规范，项目创建时默认创建 `dev/`、`dev-doc/` 根目录；创建具体目标开发工作区时，只创建 `dev/<target>-dev/` 和 `dev-doc/<target>-doc/` 目标代码文档区，不再复制第二套开发规范或开发账本。
6. 启用后，项目必须同时遵守 `common` 全局体系规范和项目本地体系规范。开发体系在未创建具体目标开发工作区前，先遵守 `common/dev-doc` 全局开发规范。
7. 项目本地体系规范默认可以很短，只引用 common 规范并记录项目专属补充。

项目管理员必须在项目根目录 `项目配置清单.md` 中记录：

1. 已启用体系。
2. 对应目录。
3. 适用角色。
4. 本地规范入口。
5. AI 角色、权限边界和工作空间。

一句话：`common` 是插件库，项目根目录 `项目配置清单.md` 是项目装了哪些插件、谁来做、目录在哪里的清单。

## 4. 文件管理规范

### 4.1 文件创建

除临时文档外，所有正式文档类文件创建后，文件头部必须包含：

1. 创建人员。
2. 文件职责：该文件负责记录什么内容。
3. 管理规范或模板。
4. 引用的关键文件。
5. 记录方式：append-only、覆盖式、版本式或其他方式。

新增正式文档后，必须同步更新所在目录的导读、索引或入口文档。

如果所在目录没有导读或索引，项目管理员或当前执行者应补一个轻量入口，至少说明本目录关键文件和子目录作用。

代码、数据表、图片、压缩包、二进制产物不强制写文件头，但必须能通过相邻 README、manifest、索引表、执行日志或结果包说明追到职责、来源、生成方式和引用关系。

### 4.2 文件修改

修改文件时必须遵守：

1. 不得破坏文件原有结构。
2. 不得静默删除仍有效的历史结论。
3. 修改后应检查是否产生重复、冲突、断链或引用失效。
4. 正式文档引用其他文件时，默认使用相对路径。
5. 不得新增依赖个人机器的绝对路径，除非跨项目、跨磁盘引用不可避免，并写明原因。

### 4.3 文件删除、改名、移动

文件改名或移动，按“删除旧文件 + 创建新文件”处理。

必须同步完成：

1. 更新引用该文件的所有文档。
2. 更新所在目录导读或索引。
3. 如果是正式产物，记录迁移原因。
4. 如果旧路径被历史结果包引用，不得直接删除，应保留迁移说明或兼容入口。

### 4.4 临时文件

临时文件必须进入对应体系的 `tmp/` 目录或项目约定的临时目录。

临时文件包括：

1. 一次性脚本。
2. 临时中间表。
3. 临时图片。
4. 临时检查输出。
5. 临时草稿。
6. 临时压缩包。

正式目录只放正式文档、正式代码、正式数据或稳定归档入口。

### 4.5 编码和格式

文本文件默认使用 `UTF-8`。

PowerShell、Python 或其他脚本读写文本时，应显式使用 UTF-8。

在 Windows / PowerShell 环境读取中文 Markdown 或中文文本时，必须显式指定编码，避免默认编码导致乱码和误读。例如：

```powershell
Get-Content -Encoding UTF8 <path>
Select-String -Path <path> -Pattern <pattern>
```

如果需要先确保控制台输出为 UTF-8，可在命令前设置：

```powershell
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
```

遇到历史非 UTF-8 文件时：

1. 不得按错误编码直接回写。
2. 先判断编码风险。
3. 必要时先转码或只读。

## 5. 目录和文件夹管理规范

### 5.1 根目录

`manage_system` 根目录只放：

1. 全局规范。
2. 管理体系说明。
3. 公共目录 `common/`。
4. 数据根目录 `data/`。
5. 项目目录。
6. 必要的全局建议或索引文档。

不得把具体项目的临时脚本、临时结果、业务数据散落到根目录。

### 5.2 common 目录

`common/` 存放通用体系规范、模板和公共资产。

推荐结构：

```text
common/
  project-doc/  项目规范、项目创建、项目审计规范
  pro-doc/      需求、策略规范
  dev-doc/      开发体系、编码、测试、代码审核规范
  exp-doc/      实验规范、实验模板、实验审核规范
  data-doc/     数据存储、数据样本、数据字典规范
  ana-doc/      案例分析规范
  ai-workplace/ AI 工作空间创建、角色指派、工作说明生成指南
```

`common/` 下不得写入具体项目专属结论、业务样本、项目路径或历史运行包。

### 5.3 项目目录

一个项目一个项目目录。

项目目录至少应包含：

1. `项目规范.md`
2. `项目配置清单.md`。
3. 已启用体系对应的目录。
4. AI 工作空间目录。

项目启用某个体系后，才需要创建对应体系目录。

典型体系目录：

```text
dev/        开发代码根目录；具体代码放 dev/<target>-dev/
dev-doc/    开发文档根目录；根级开发账本和规范放 dev-doc/；目标代码文档和方案附件放 dev-doc/<target>-doc/
pro-doc/    需求文档、策略说明、业务规则说明
exp-doc/    实验文档
exp-data/   实验数据和结果包
ana-doc/    案例分析文档
ana-data/   案例分析数据和图片
tmp/        项目级临时文件
```

开发体系比较特殊：开发角色必须绑定目标体系或目标事项。常见映射是 `dev/pro-dev/` + `dev-doc/pro-doc/`、`dev/exp-dev/` + `dev-doc/exp-doc/`、`dev/ana-dev/` + `dev-doc/ana-doc/`。不得把所有代码直接堆到 `dev/` 根目录。

### 5.4 本地规范入口

项目启用体系时，应创建本地体系规范。

例如启用实验体系时：

1. `exp-doc/实验规范.md`
2. `exp-doc/实验审计规范.md`

本地体系规范必须引用 common 对应规范，并声明：

1. 本项目所有相关 AI 同时遵守 common 规范和本地规范。
2. 本地规范可以补充项目特化规则，也可以设计本地事项流程。
3. 本地流程必须先满足全局硬约束和 common 体系硬约束，并通过对应审核。
4. 已审核通过的本地流程，执行时优先于 common 默认流程。
5. 本地规范不得重复抄写 common 规范正文，只记录项目特化补充、流程覆盖说明和例外。

## 6. AI 角色和权限规范

### 6.1 角色权限

所有 AI 的权限跟角色走。

这里的权限是协作约束，不等同于操作系统或工具实际权限。即使工具层面能写某个文件，AI 也必须按角色权限边界执行。

同一个 AI 拥有多个角色时，权限取角色权限并集。

默认角色：

1. 项目管理员：项目根目录管理权限。
2. 需求 AI：`pro-doc/` 写权限，负责需求、策略和业务规则文档。
3. 开发 AI：按目标体系绑定 `dev/<target>-dev/`、`dev/<target>-dev/test/`、`dev-doc/<target>-doc/` 写权限；不默认拥有所有开发子目录写权限。
4. 实验员：`exp-doc/`、`exp-data/` 写权限。
5. 案例分析员：`ana-doc/`、`ana-data/` 写权限。
6. 审核员：主写对应审计报告；如审计问题需要跨轮跟踪，只在问题记录中写索引或关联，不直接改被审计产物。

所有 AI 默认拥有项目内所有文件的读权限。

### 6.2 工作空间

每个 AI 在项目中应有自己的工作空间目录。

工作空间目录必须统一使用 `ai-<name>/` 命名，`<name>` 使用稳定英文名或拼音小写。例如 Andrew 使用 `ai-andrew/`，Codex 使用 `ai-codex/`。禁止直接使用裸 AI 名目录，例如 `Andrew/`、`Codex/`。

创建 AI 工作空间、分配角色、生成 `工作说明.md` 和 `项目问题反馈.md` 时，按 `common/ai-workplace/AI工作空间创建指南.md` 执行，并同步更新项目根目录 `项目配置清单.md`、`项目执行日志.md` 和 `项目变更记录.md`。

工作空间用于：

1. 临时分析。
2. 草稿。
3. 私有中间产物。
4. 未进入正式体系的探索材料。
5. 重大协作问题和反复返修问题的私有反馈入口。

`项目问题反馈.md` 不替代正式审计报告、项目问题记录或执行日志；具体边界按 `common/project-doc/项目规范.md` 和 `common/ai-workplace/AI工作空间创建指南.md` 执行。

AI 对自己的工作空间有读写权限。

工作空间内产物如果进入正式事项，必须迁入对应正式目录，并登记到导读、总纲、执行日志或结果索引中。

### 6.3 审核员边界

审核员负责判断事项是否符合目标、流程、证据和规范。

审核员默认可以：

1. 读取证据链上的文档、数据、脚本和产物。
2. 运行必要的只读审计脚本。
3. 写审计报告。
4. 在需要跨轮跟踪时写问题记录索引或关联。
5. 要求执行者补证据、修复或重跑。

审核员默认不得：

1. 直接改写被审计主产物。
2. 直接替执行者修改业务主表。
3. 用自己的补丁掩盖执行问题。
4. 把边角料问题升级成阻断问题。

如果审核员必须临时修复工具脚本，应明确标记为“审计辅助脚本”，不能冒充执行方正式产物。

## 7. 项目根目录 `项目规范.md` 规范

每个项目根目录必须有 `项目规范.md`。

`项目规范.md` 至少记录：

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

`项目规范.md` 不应复制全局规范或 common 体系规范正文，只记录项目目标、边界、配置入口和项目特化补充。体系启用、目录映射、角色权限和工作空间记录在 `项目配置清单.md`；体系内部流程、字段、模板、审核细则应放在对应体系规范里。

## 8. 事项管理规范

所有事项都必须能追踪。正式事项必须完整记录，临时事项可以轻量记录，但也必须留下最小证据链。

事项必须能回答：

1. 事项为什么出现。
2. 事项目标是什么。
3. 谁负责。
4. 设计或计划是什么。
5. 实际执行了什么。
6. 关键数据在哪里。
7. 结果是什么。
8. 审计是否通过。
9. 如果失败，为什么失败，如何修复。

事项类型可以包括：

1. 需求事项。
2. 需求事项。
3. 编码事项。
4. 实验事项。
5. 数据事项。
6. 案例分析事项。
7. 审计事项。
8. 项目管理事项。

不同体系可以有自己的总纲、设计、执行日志和审计报告，但必须能通过统一 ID 串起来。

## 9. 证据链规范

所有事项至少应形成证据链。正式事项要求完整证据链；临时事项允许轻量证据链，但不能完全无记录。

正式事项证据链：

```text
来源聊天记录 / 上游文档
-> 事项总纲 / 目标记录
-> 事项设计 / 执行计划
-> 执行日志
-> 中间数据 / 结果包
-> 审计报告
-> 问题记录索引（仅在需要跨轮跟踪或非审计问题进入闭环时）
-> 修复复验
-> 结论回写
```

关键来源聊天记录必须进入事项背景或被明确路径引用。

如果实际事项和聊天要求不一致，审核员必须指出。

不能只在聊天中解释关键背景，而不落到正式文档。

临时事项最低证据链：

```text
来源 / 目的
-> 执行了什么
-> 产物在哪里
-> 当前结论或是否废弃
```

临时事项一旦被后续引用、进入交付、影响结论或被纳入正式结果，必须补齐为正式事项证据链。

## 10. 审核规范

审核的目标是发现真问题，不是制造流程负担。

审核员必须检查：

1. 目标是否清楚。
2. 设计是否能满足目标。
3. 执行是否按设计进行。
4. 数据和产物是否对得上。
5. 关键证据链是否可追踪。
6. 结论是否超过证据。
7. 是否存在会影响结论的 bug、偏差或流程错位。

审核员不得把以下问题升级为阻断：

1. 不影响结果的命名差异。
2. 不影响实现分叉的文档措辞问题。
3. 低影响格式问题。
4. 非核心可读性建议。
5. 不影响主流程的诊断项缺失。

审核复杂事项时，可以拆分审计步骤，也可以使用 subagent，但必须由主审核员整合判断，不得直接转发未经复核的碎片结论。

## 11. 真 Bug 和问题归因规范

发现问题时必须先归因。

问题类型：

1. 需求问题。
2. 代码问题。
3. 数据 / 产物问题。
4. 流程 / 调度问题。
5. 实验设计问题。
6. 审计问题。
7. 待归因。

真 bug 必须至少满足一项：

1. 会导致结果、结论、发布判定、交易或研究读法错误。
2. 会导致正式产物误放行、误失败或误读。
3. 会导致数据丢失、重复、错连、断链或不可复现。
4. 会导致流程顺序错误、重跑错误或复用错误。
5. 会导致全量运行卡死、内存爆、无限重跑或长时间不可观察。
6. 会导致实验设计缺关键对照、样本错、未来函数或结论不可读。

不应记为 bug 的内容：

1. 内部变量名和需求字段名不同，但输出合同稳定且映射清楚。
2. 文档措辞不优雅，但不会导致实现分叉。
3. legacy alias 存在，但与 canonical 字段有明确映射。
4. 低影响清理项、格式项、非阻断优化项。

需求问题必须谨慎判定。只有需求缺字段合同、口径冲突、主链边界不清、验收规则不清，并足以导致实现分叉或验收误判时，才判为需求问题。

## 12. 问题记录和关闭规范

问题记录是非审计来源问题的主记录入口，也是审计问题跨轮跟踪时的索引入口。

审计人员在设计审核、执行审核、复审中发现的问题，主记录必须写入对应审计报告；只有当该问题需要跨轮跟踪、跨事项汇总或后续由非审计角色长期处理时，才在问题记录中建立索引或关联，不重复全文。

非审计人员发现的问题，例如执行者、实验员、案例分析员、项目管理员、开发 AI 或人工同事反馈的问题，主记录写入问题记录；如后续进入审计复核，应在问题记录中引用对应审计报告 ID。

问题记录至少包含：

1. 问题 ID。
2. 问题类型。
3. 严重级别。
4. 证据。
5. 影响。
6. 修复建议。
7. 责任方。
8. 当前状态。
9. 复验结论。
10. 来源类型：非审计反馈 / 审计问题索引。
11. 关联审计 ID：审计问题索引必须填写，非审计反馈可写无。

问题关闭必须有复验。

不能因为“已经改了”就关闭。

如果问题反复出现，应优先检查：

1. 是否修错层级。
2. 是否应该抽公共入口。
3. 是否需求本身不清。
4. 是否测试只覆盖当前错误行为。
5. 是否问题记录缺少明确修复方案。

## 13. 需求、编码、实验的默认关系

### 13.1 需求

需求文档必须服务实现和验收。

小需求走轻流程；系统需求走完整流程。

需求必须审核通过后才算完成。

### 13.2 编码

轻量代码可以不写完整编码方案，但必须自测和自检。

重型、多模块、长流程或公共能力开发，必须先写代码编写方案，并经过审核员审核通过后再编码。

### 13.3 实验

实验是事项类型。

实验必须有目标、设计、执行日志、结果包、审计报告和结论边界。

是否需要防未来函数，应根据实验目标判断，不得机械套用。

## 14. 全局数据入口规范

所有 AI 需要使用全局公共数据时，必须先看根目录下两个入口文档：

1. `全局存储体系.md`：说明当前有哪些全局数据源、每个数据源是什么、哪些表属于全局公共表、哪些表只是专题研究表、数据库连接口径、数据源之间的关系和使用边界。
2. `全局数据格式.md`：说明全局公共表和公共文件型数据的字段级 schema，包括字段名、字段类型、主键 / 约束、字段含义和使用注意。

默认使用规则：

1. 新实验、新案例分析、新开发模块需要读行情、K 线、市场广度、股票画像、市值、股本、换手等公共数据时，先按 `全局存储体系.md` 选择数据源。
2. 写 SQL、读 CSV、设计数据接口、写需求字段合同时，先按 `全局数据格式.md` 核对字段和主键，不得凭记忆猜字段。
3. 如果使用的表没有在 `全局存储体系.md` 中纳入公共表，必须在事项文档里说明它是临时表、专题研究表、私有产物还是待升格公共表。
4. 如果发现数据库已有新公共表或公共表新增字段，必须同步更新 `全局存储体系.md` 和 `全局数据格式.md`，再让其他 AI 依赖该表。
5. 全局数据源的账号、密码、连接方式按 `全局存储体系.md` 的口径执行；不得在新事项文档里复制扩散明文密码。

一句话：找全局数据先看 `全局存储体系.md`，写字段和接口先看 `全局数据格式.md`。

## 15. 数据和校验规范

数据校验必须轻重分层。

主流程只保留核心校验：

1. 必需输入存在。
2. 必需字段存在。
3. 关键 key 合法。
4. 输出可读。
5. 行数明显合理。
6. 上下游 handoff 不断。

复杂校验应放到只读 helper：

1. helper 读取已落盘产物。
2. helper 输出 summary、report、readout。
3. helper 不改业务主表。
4. helper 不改 manifest、receipt、fingerprint。
5. helper 不反向覆盖主流程状态。

不得为了“看起来严谨”不断增加 gate，把主流程拖成验证系统。

## 16. 重跑、缓存和失败产物规范

长流程必须记录重跑原则：

1. 何时从原始数据重跑。
2. 何时从中间快照重跑。
3. 哪些产物可复用。
4. 复用前检查哪些 schema、row_count、key、配置和版本。
5. 失败产物如何标记。

不得只靠文件存在判断可复用。

半成品、空壳文件、失败包不得被下游当成正式完成产物。

## 17. 汇报规范

对用户汇报时，默认先说结论。

正式汇报应包含：

1. 当前做了什么。
2. 是否发现问题。
3. 问题是否阻断。
4. 当前能读成什么。
5. 当前不能读成什么。
6. 下一步最小动作是什么。

不得用空泛标签代替大白话结论。

不得把“代码能跑”“测试通过”“summary 好看”直接说成“事项通过”。

## 18. 禁止事项

禁止：

1. 把具体项目内容写进 `common/` 或全局规范。
2. 未启用体系就要求项目创建该体系全部文档。
3. 本地规范和 common 规范冲突。
4. 不看目标就审计。
5. 把边角料升级成阻断。
6. 用诊断 helper 反向改写主流程。
7. 用未来数据冒充实时决策。
8. 用 proxy 冒充原口径。
9. 不记录来源聊天就开始执行复杂事项。
10. 问题未复验就关闭。

## 19. 变更规则

修改本文件时必须遵守：

1. 说明为什么改。
2. 判断是否影响已有项目。
3. 如果影响已有项目，给出迁移口径。
4. 不得因为某个项目的临时问题，把全局规范改得过重。
5. 如果只是执行者个人失误，不应上升成全局硬规则。

## 20. 当前核心口径摘要

1. 体系是插件，用不用由项目管理员决定。
2. 项目体系和开发体系默认随项目创建；其他体系由项目管理员按需启用。
3. 启用体系后，项目必须遵守 common 规范和本地规范；开发体系在未创建具体目标开发工作区前，先遵守 common/dev-doc 全局开发规范。
4. 正式文档必须有职责、引用、记录方式和目录入口；非文档产物必须能通过 manifest、索引或日志追溯。
5. 权限跟角色走，审核员不直接改被审计产物。
6. 开发体系绑定目标体系，代码放 `dev/<target>-dev/`，目标代码文档和方案附件放 `dev-doc/<target>-doc/`；正式开发账本统一放 `dev-doc/` 根目录。
7. 所有正式事项必须有目标、过程、结果和审计证据链。
8. 审核抓真问题，不吹毛求疵，不层层加码。
9. 问题必须归因，关闭必须复验。
10. 主流程校验要轻，复杂校验放只读 helper。
11. 具体项目内容不得污染全局或 common。
12. 项目本地规范可以补充规则和设计本地流程；已审核通过的本地流程优先执行，但不能削弱全局规范和 common 体系硬约束。
13. 全局公共数据入口是 `全局存储体系.md` 和 `全局数据格式.md`；读数据先找数据源，写字段先核 schema。