edit | blame | history | raw

实验环境创建指南

创建人员：Codex
文件职责：指导 AI 在任意项目中按 common/exp-doc 创建一个可工作的实验员实验环境。
管理规范/模板：common/exp-doc/实验规范.md；common/exp-doc/实验存储体系创建指南.md。
引用文件：实验规范.md；实验总纲模版.md；实验设计模版.md；实验执行日志模版.md；实验审核规范.md；实验审计报告模版.md；实验问题记录模版.md。

1. 目标

本指南用于回答：

一个 AI 拿到 common/exp-doc 后，如何在项目目录里创建实验体系，让实验员能按规范开始工作。

目标不是把所有实验都做重，而是保证最关键的入口、证据链、存储位置和审核闭环可用。

默认口径：实验员和实验开发员可由同一个 AI 承担；实验审核员和实验开发审核员也可由同一个 AI 承担。实验开发的审核结论统一写入 exp-doc/实验审计报告.md，不另写到 dev-doc/开发审计报告.md。

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

创建实验环境前，至少确认：

项 说明
project_root 项目根目录
project_name 项目名称
experiment_owner 默认实验员或执行 AI
auditor_owner 默认审核员或审核 AI
data_storage_mode 文件系统 / 数据库 / 混合；不确定可先用文件系统
initial_experiment_scope 是否立即创建第一个实验事项

如果这些信息不完整，可以先创建空实验环境，但必须在项目级导读里标记待补。

3. 项目目录结构

推荐创建：

<project_root>/
  exp-doc/
    目录导读.md
    实验规范.md
    实验审计规范.md
    实验存储体系.md
    实验审计报告.md
    实验问题记录.md
    实验总纲.md
    实验设计.md
    实验执行日志.md
  exp-data/
    raw/
    result/
    img/
    tmp/

如果项目已有文档目录或数据目录，可以映射到既有结构，但必须在 实验存储体系.md 里写清楚映射关系。

4. 项目级文件职责

文件 来源 职责
exp-doc/目录导读.md 可手写 说明项目实验目录结构和关键入口
exp-doc/实验规范.md 必建 项目本地实验规范；默认只引用 common 实验规范，且不得冲突
exp-doc/实验审计规范.md 必建 项目本地实验审核/审计规范；默认只引用 common 实验审核规范，且不得冲突
exp-doc/实验存储体系.md 实验存储体系创建指南.md 项目级数据目录、结果包、schema 和读取规则
exp-doc/实验审计报告.md 实验审计报告模版.md 设计审核、执行审核、复审记录，可追加维护
exp-doc/实验问题记录.md 实验问题记录模版.md 非审计来源实验问题闭环；审计问题只记录跨轮跟踪索引

项目级文件是实验环境的底座。实验总纲.md、实验设计.md、实验执行日志.md 是项目内持续追加的实验账本，不是每个实验单独一份文件。

common/exp-doc/实验规范.md 和 common/exp-doc/实验审核规范.md 是全局通用规范。项目必须创建本地 实验规范.md、实验审计规范.md，默认内容可以很短，只引用 common 规范并声明必须遵守；如果项目后续要补本地规则，只能做项目特化补充，不能与 common 规范冲突。项目内所有实验员和审核员必须同时遵守 common 规范和项目本地规范。

如果本地规范和 common 规范冲突，必须先修本地规范；冲突未解决前，不应把受影响实验标为完成。

创建全新项目时，不得把其他项目的专有路径、业务名词、历史实验名、旧模块名或旧数据口径带进新项目。模板实例化时，示例内容必须改成当前项目自己的中性命名；如果只是验证环境，可使用 OBJECT001、event_date、轻量时序图 smoke 这类通用名称。

4A. 模板实例化规则

创建项目实验环境时，不要直接修改 common/exp-doc 下的模板文件。

应按以下方式实例化：

common 文件 项目内实例化位置 说明
实验总纲模版.md exp-doc/实验总纲.md 项目内所有实验背景、目标、边界、状态和结论的总账本
实验设计模版.md exp-doc/实验设计.md 项目内所有实验设计、步骤、产物和判定标准的设计账本
实验执行日志模版.md exp-doc/实验执行日志.md 项目内所有实验 run、输入、关键中间过程、中间数据路径、输出、异常和自检的执行账本
实验审计报告模版.md exp-doc/实验审计报告.md 项目内所有设计审核、执行审核和复审记录
实验问题记录模版.md exp-doc/实验问题记录.md 项目内非审计实验问题闭环；审计问题只做索引

原则：

  1. 模板实例化后，要把占位符替换成项目和实验的真实信息。
  2. 如果暂时不知道某项，写 待补，不要留空。
  3. 项目内实验文档默认集中维护；新实验追加到 实验总纲.md、实验设计.md、实验执行日志.md，不要默认创建 <EXP-ID>_实验总纲.md 这类单实验文件。
  4. 结果包不实例化模板，只按 实验存储体系.md 创建目录和 manifest/readout。
  5. 文档引用项目内文件时默认使用相对路径，不要硬编码本机绝对路径。只有跨项目或跨磁盘引用时才允许写绝对路径，并说明原因。
  6. 实验总纲.md、实验设计.md、实验执行日志.md、实验审计报告.md、实验问题记录.md 都按 append-only 滚动账本维护，最新记录追加到文件末尾。文件开头只放当前总览和固定口径，不放最新实验全文。

5. 创建步骤

5.1 创建目录

创建 exp-doc/ 和 exp-data/ 下的基础目录。

tmp/ 只能放临时文件，不能作为正式结论入口。

5.2 创建项目级实验入口

创建：

  1. exp-doc/目录导读.md
  2. exp-doc/实验规范.md
  3. exp-doc/实验审计规范.md

项目入口至少要能让人看到：

  1. 当前有哪些实验。
  2. 每个实验做到哪一步。
  3. 总纲、设计、日志、结果包、审计报告在哪里。
  4. 当前结论和下一步是什么。

这些信息可以写在项目总索引或 exp-doc/目录导读.md，不需要单独创建实验总纲列表。

exp-doc/目录导读.md 最低应包含：

  1. 本项目实验目录结构。
  2. 当前实验总纲入口列表或项目总索引入口。
  3. 实验存储体系入口。
  4. 实验审计报告入口。
  5. 实验问题记录入口。

每次新增实验、完成实验、重跑关键 run 或更新结果包后，都应同步更新 exp-doc/目录导读.md 的实验入口和当前结论。目录导读不是结论主账本，但它必须能让人快速找到最新总纲、设计、执行日志、结果包、审计报告和问题记录；如果目录导读滞后，应按总纲和设计补齐。

exp-doc/实验规范.md 最低应包含：

  1. 采用的 common 实验规范路径。
  2. 明确本项目所有实验员必须遵守 common 实验规范和本文件。
  3. 本项目核心实验文档的作用和入口，至少说明 实验总纲.md、实验设计.md、实验执行日志.md、实验存储体系.md、实验审计报告.md、实验问题记录.md。
  4. 本项目是否有特殊目录映射。
  5. 本项目是否有特殊数据存储方式。
  6. 本项目实验员的默认分工。
  7. 本项目对轻量实验、正式实验的区分口径。
  8. 如有本地补充规则或本地实验流程，明确其不得削弱 common 实验规范硬约束；流程通过审核后，执行时以本地流程为准。

exp-doc/实验审计规范.md 最低应包含：

  1. 采用的 common 实验审核规范路径。
  2. 明确本项目所有审核员必须遵守 common 实验审核规范和本文件。
  3. 本项目审核员的默认分工。
  4. 本项目审计报告记录位置。
  5. 如有本地补充审核规则或本地审核流程，明确其不得削弱 common 审核规范硬约束；流程通过审核后，执行时以本地流程为准。

项目本地 实验规范.md 初始内容可以只有：

# 实验规范

创建人员：<填写>
文件职责：记录本项目实验员必须遵守的实验规范。本文件引用 common/exp-doc/实验规范.md，不得削弱 common 实验规范硬约束。
管理规范/模板：common/exp-doc/实验规范.md
引用文件：<相对路径或明确的 common 规范路径>

## 1. 基本口径

本项目所有实验员必须同时遵守 common/exp-doc/实验规范.md 和本文件。

本文件当前没有额外补充规则。如后续设计本地实验流程，必须满足 common 实验规范硬约束；流程通过审核后，执行时以本地流程为准。

## 2. 核心实验文档作用

| 文档 | 作用 |
|---|---|
| 实验总纲.md | 记录本项目所有实验事项的背景、目标、边界、状态、结果包入口和结论 |
| 实验设计.md | 记录本项目所有实验的设计、步骤、依赖、产物和判定标准 |
| 实验执行日志.md | 记录本项目所有实验 run、输入、关键中间过程、中间数据路径、输出、异常、自检和重跑 |
| 实验存储体系.md | 说明实验数据、结果包、图片、表 schema 和读取追踪方式 |
| 实验审计报告.md | 记录设计审核、执行审核和复审结论 |
| 实验问题记录.md | 记录非审计来源实验问题、影响、修复建议和复验状态；审计问题只记录索引 |

项目本地 实验审计规范.md 初始内容可以只有：

# 实验审计规范

创建人员：<填写>
文件职责：记录本项目审核员必须遵守的实验审计规范。本文件引用 common/exp-doc/实验审核规范.md，不得削弱 common 实验审核规范硬约束。
管理规范/模板：common/exp-doc/实验审核规范.md
引用文件：<相对路径或明确的 common 审核规范路径>

## 1. 基本口径

本项目所有审核员必须同时遵守 common/exp-doc/实验审核规范.md 和本文件。

本文件当前没有额外补充规则。如后续设计本地实验审核流程，必须满足 common 实验审核规范硬约束；流程通过审核后，执行时以本地流程为准。

5.3 创建项目级存储体系

按 实验存储体系创建指南.md 创建 exp-doc/实验存储体系.md。

最低要求：

  1. 写清数据目录。
  2. 写清结果包命名规则。
  3. 写清图片、表格、日志的存放规则。
  4. 写清核心表 schema 的记录方式。
  5. 写清如何从实验总纲追到结果包，再追到原始证据。
  6. 写清需要长期复核的中间数据放在哪里；默认建议放在 exp-data/result/<run_id>/intermediate/，不要把 exp-data/tmp/ 当正式证据入口。

5.4 创建项目级审核和问题闭环文件

创建：

  1. exp-doc/实验审计报告.md
  2. exp-doc/实验问题记录.md

这两个文件可以先为空模板，但必须存在，方便后续追加记录。

5.5 创建第一个实验事项

如果要立即启动实验，创建：

  1. 在 实验总纲.md 中追加该实验的背景、目标、边界和入口。
  2. 在 实验设计.md 中追加该实验的设计、步骤、产物和判定标准。
  3. 在 实验执行日志.md 中追加该实验的 run 记录、输入、关键中间过程、中间数据路径、输出和自检。

并在项目总索引或 exp-doc/目录导读.md 登记入口；如果没有项目总索引，也可以只保证 实验总纲.md 文件路径清晰可找到。

追加位置必须是文件末尾，保持“越往后越新”的阅读习惯。不要为了让最新内容显眼而插到文件开头；需要快速入口时，更新文件开头的“当前总览”即可。

实验设计必须审核通过后才能执行。执行完成后必须进入执行审核，审核通过后才能标记实验完成。

6. 命名建议

实验 ID：

EXP-YYYYMMDD-主题短名-序号

run ID：

RUN-YYYYMMDD-主题短名-序号

结果包目录：

exp-data/result/<run_id>/

图片目录：

exp-data/img/<experiment_id>/<run_id>/

7. 体系创建校验方案

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

7.1 目录和文档校验

检查：

  1. exp-doc/、exp-data/raw/、exp-data/result/、exp-data/img/、exp-data/tmp/ 都存在。
  2. 目录导读.md、实验规范.md、实验审计规范.md、实验存储体系.md、实验审计报告.md、实验问题记录.md、实验总纲.md、实验设计.md、实验执行日志.md 都存在。
  3. 每个正式文档都有：创建人员、文件职责、管理规范/模板、引用文件、记录方式。
  4. 本地 实验规范.md 和 实验审计规范.md 明确引用 common 对应规范，并说明不得削弱 common 硬约束。
  5. 不存在从其他项目复制来的具体实验、旧结果包、旧路径或旧业务结论。

7.2 项目配置和存储校验

检查：

  1. 项目根目录 项目配置清单.md 已登记实验体系启用状态、目录、common 规范、本地规范、实验员和实验审核员。
  2. 项目执行日志记录了启用实验体系的动作。
  3. 如启用实验体系改变了项目配置或目录，项目变更记录已登记。
  4. 实验存储体系.md 能说明实验数据、结果包、图片、临时文件存放位置和读取方式。
  5. 实验存储体系.md 能说明结果包和核心中间数据如何从 实验总纲.md、实验设计.md、实验执行日志.md 追踪。

7.3 证据链 dry-run 校验

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

最小链路应能串起来：

实验总纲：记录 EXP-SMOKE-001 的来源、目标、边界
-> 实验设计：记录 DESIGN-SMOKE-001 的实验设计、步骤、产物和判定标准
-> 实验执行日志：记录 RUN-SMOKE-001 的关键步骤和产物位置；如无真实产物，明确 dry-run
-> 实验审计报告：记录 AUDIT-SMOKE-001 的初始化 / dry-run 审计结论
-> 实验问题记录：仅在存在非审计来源问题或需要审计问题索引时使用

通过标准：

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

7.4 校验结果记录

校验结论写入 实验审计报告.md 的初始化审计记录。

如果发现问题：

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

8. 实验员开始工作前的 ready 检查

实验环境 ready 的最低标准：

检查项 必须满足
目录存在 exp-doc/、exp-data/raw/、exp-data/result/、exp-data/img/、exp-data/tmp/ 存在
入口存在 项目总索引、exp-doc/目录导读.md 或具体实验总纲入口至少存在一个
本地规范存在 实验规范.md、实验审计规范.md 存在，且引用 common 规范
存储规则存在 实验存储体系.md 存在
审核入口存在 实验审计报告.md 存在
问题闭环存在 实验问题记录.md 存在
第一个实验 如已启动，必须已追加到 实验总纲.md、实验设计.md、实验执行日志.md
证据链字段 experiment_id、step_id、run_id、audit_id 的使用规则已明确
路径口径 项目内引用默认使用相对路径；不得默认写本机绝对路径

体系创建校验通过后，实验员才允许开始正式实验事项。

9. 工作原则

  1. 先有目标，再有设计，再执行。
  2. 设计和执行都要审核。
  3. 结果包是目录，不是模板文档。
  4. 结论必须回写到总纲和审计报告。
  5. 数据校验要轻，不要把实验体系做成重型 gate。
  6. 审核抓真问题，不为模板完整性吹毛求疵。
  7. 如果实验目标来自聊天，关键聊天记录必须进入实验总纲背景。

9. 不要做的事

  1. 不要只创建结果包，不创建总纲和设计。
  2. 不要只写“已跑完”，不写输入、关键中间过程、中间数据路径、输出、关键计数。
  3. 不要把临时文件当正式结果。
  4. 不要让审计报告替代实验设计。
  5. 不要把所有实验都强行加未来函数检查；是否需要由实验目标决定。
  6. 不要把小实验做成重型工程流程；轻量实验也要有目标、边界、结果入口和结论边界。
  7. 不要把滚动账本写成每个实验一份孤立表单；长期实验文档必须能顺着时间往下读。

10. 初始化交付清单

AI 创建完实验环境后，应在回复或交付记录里列出：

项 内容
项目根目录 <project_root>
已创建目录 exp-doc/、exp-data/raw/、exp-data/result/、exp-data/img/、exp-data/tmp/
项目级文档 目录导读.md、实验规范.md、实验审计规范.md、实验存储体系.md、实验审计报告.md、实验问题记录.md、实验总纲.md、实验设计.md、实验执行日志.md
首个实验记录 如已创建，说明已追加到实验总纲、实验设计、实验执行日志的位置
待补事项 没有确认的信息、没有创建的实验、待审核的设计
是否 ready 是/否，并说明原因

只有满足第 7 节 ready 检查时，才能说实验员实验环境已经可用。