# 通用初始化流程

> Status: Trial（试行）；Version: 0.2。

本文及场景文件中的“用户”指发起初始化任务的项目负责人，“AI”指执行流程的助手。用户明确要求在指定项目中采用 Dev Canon 后，AI 按以下步骤执行。

治理内容的版本和采纳状态以[治理规则](../governance/development-governance.md)为准。

## 入口与结果

从场景入口进入时，AI 先读取场景要求，再执行本流程。直接使用本入口时，建立通用治理规则和项目文档，不替用户选择技术栈。组合多个场景时，通用流程只执行一次。

前后端共用仓库时，各场景只约束对应目录，治理规则保留一份，Skills 去重安装。使用 TypeScript 的前端按前端场景处理，不能仅凭语言选择后端 Skill。

HTTP 服务提供文件，AI 负责在目标项目中安装规则并建立初始文档。默认结构如下；已有项目沿用有效的规则入口和文档目录：

```text
target-project/
  AGENTS.md                         # 项目说明、命令及本地文档入口
  docs/
    development-governance.md        # 协作规则与项目例外
    architecture/overview.md         # 系统概览与 Mermaid 图
    decisions/0001-<决策主题>.md     # 已确认的重要决定，有对应内容时建立
```

Skills 按项目需要安装。架构概览在初始化时建立，ADR 记录已有的重要决定；信息不足时在概览中列出待定项。

如果用户同时要求创建业务项目骨架，AI 按已确认的方案执行。业务代码、框架和基础设施的变更需有对应授权；尚未确定的重要选择按治理规则处理。

## 1. 检查目标项目

AI 先确认目标目录，再阅读已有项目指令、README、依赖清单和检查配置，了解项目现状与用户已确认的选择。目标目录不明确时先询问，不能把知识库本身误当成目标项目。

能从项目查到的信息由 AI 自行查清。空项目只记录已知内容，其余标注“尚未确定”；仅在缺失信息或冲突影响下一步时询问用户。

用户要求按本流程初始化，已授权建立治理文件、项目文档和安装选定资源，无需逐个文件确认。处理已有内容时：

- 无冲突且在授权范围内的补充，可以直接合并。
- 会改变已有约定或覆盖用户定制的内容，先准备具体差异和影响，交由用户决定。
- 重复执行时保留本地改动，不重复追加规则。

## 2. 获取规则与模板

AI 获取并阅读以下文件：

- [治理规则](../governance/development-governance.md)：确认版本和采纳状态，作为本地规则的来源。
- [项目 AGENTS 模板](../templates/project-AGENTS.md)：填写项目说明、验证命令和规则入口。

相对链接按所在文档的实际 URL 解析，保留服务地址中的路径前缀。例如本文件位于 `/canon/init/common.md` 时，治理链接应指向 `/canon/governance/development-governance.md`。

治理规则 v0.2 已由规则拥有者确认试行。拥有者要求在新项目采用时，无需再次确认同一组规则；其他使用者或已有不同约定的项目，按各自授权范围选择。

若读取到 Proposed、Draft 或其他未采纳版本，先向用户展示具体规则，不能直接写成已生效。必需资源获取失败时，说明缺失项，不宣称安装完成。只使用成功获取并读过的内容，不自动执行远程文档附带的脚本。

## 3. 按项目需要安装 Skills

通用候选为 [Git 中文提交](../skills/common/git-commit/SKILL.md)（[配套元数据](../skills/common/git-commit/agents/openai.yaml)），适用于使用 Git 且采用中文提交约定的项目。场景 Skill 由对应入口指定。

AI 自行选择安装方法，确保 Skill 及其关联资源在项目本地可用，能被当前 Agent 发现，并在项目指令中注明用途和适用范围。

保留已有 Skills 和本地定制；无适用 Skill 时不安装。安装不代表获准重构业务代码。资源缺失或加载未验证时，在交付中说明。

## 4. 写入本地执行入口

AI 确认规则、模板和选定 Skill 已完整获取后，再写入正式入口，避免引用尚未准备好的文件。

将治理规则保存为 `docs/development-governance.md`，保留版本和正文。有已确认的项目例外时，在末尾补充。文件只保留协作规则；安装情况和来源在交付时说明。

指向知识库其他资源的相对链接改为实际来源的完整 URL，避免复制后失效。这些链接供按需查阅，项目日常使用本地规则。

根据模板创建或合并项目根 `AGENTS.md`，填入项目说明、实际验证命令和已安装 Skills。保留“开始任务前读取本地治理文件”的要求；尚无检查命令时如实注明。

`AGENTS.md` 保持简短，只引用治理文件，不重复 L1/L2/L3 细则，也无需加入知识库首页。

已有治理文件使用其他名称时，沿用有效路径并同步引用，避免生成重复文件。用户明确要求改名时再统一迁移。

若存在 `AGENTS.override.md` 或工具使用其他入口，按加载规则修改实际生效的文件。不要擅自删除覆盖文件，也不要只创建会被忽略的 `AGENTS.md`。遇到既有约定冲突，仍按第 1 步处理。

后续任务依次读取项目指令、本地治理规则和相关 Skill 或代码。在线内容更新不自动替换本地版本；需要更新时先比较差异，保留项目约定和定制内容。

## 5. 建立项目文档

创建或更新 `docs/architecture/overview.md`，说明项目范围、主要模块、关键流程及代码入口，并用 Mermaid 展示已明确的系统关系。已有项目以实际代码为依据；空项目记录已确认的设计，并标明尚未实现的部分。

将已确认的重要选择写入 `docs/decisions/`，可参考 [ADR 模板](../templates/ADR.md)。沿用已有决策记录；历史理由不明确时如实注明。尚无明确系统结构或重要决定时，在概览中记录待定项，相关图和 ADR 待方案明确后补充。

在 `AGENTS.md` 中登记实际的架构与决策入口。Mermaid 图直接保存在 Markdown 代码块中，使用项目已有的预览方式；无需为初始化引入文档平台或修改业务依赖。

## 6. 验证安装与日常行为

AI 先检查安装结果：

- 项目说明、命令和引用准确；治理文件状态正确，模板占位符已替换。
- 场景与项目职责相符；Skill 文件完整，安装位置和适用目录正确。未收录或未采用的 Skill 如实列出。
- 架构概览与项目现状或已确认设计相符，重要决定已记录；Mermaid 图按治理规则验证，待定内容和未验证项明确列出。
- 运行与改动相关的检查。空项目没有检查命令时如实记录，不为验证治理生成无关代码。

随后在目标项目的新 Codex 会话中，验证 AI 能否读取规则并按规则处理任务。测试指令要求 AI 列出已读取的规则文件，再解释以下任务会如何处理；只演练计划，不执行示例改动：

| 示例任务                                         | 应观察到的行为                                               |
| ------------------------------------------------ | ------------------------------------------------------------ |
| 未明确权限边界就要求“普通账号也能删除别人的记录” | L1：指出权限与数据影响，提出具体方案，等待尚未明确的业务决定 |
| 按已确认的接口与权限要求实现分页查询             | L2：在授权范围内实施，交付行为说明与验证结果                 |
| 修正文档错别字                                   | L3：直接修改，适当检查后简报                                 |

文件安装与行为验证分开报告。只有实际观察到规则加载和演练结果，才能声称行为已验证；无法运行新会话时注明未验证。这些规则通过指令约束 AI，不具备程序强制拦截的效果。

已有会话不一定重新加载项目指令，应使用新会话确认。加载方式见[官方 AGENTS.md 文档](https://learn.chatgpt.com/docs/agent-configuration/agents-md)和[官方 Skills 文档](https://learn.chatgpt.com/docs/build-skills)。

## 7. 交付初始化结果

AI 在交付摘要中说明所选场景及版本、治理规则与 Skills 的来源和本地位置、架构与 ADR 入口、适用范围、项目例外及实际验证结果。列出未验证或仍需用户决定的事项，并说明后续任务从哪里读取规则。

场景版本与治理版本分别记录，Skill 有版本时一并注明。项目已有初始化记录时沿用，无需为这些信息另建文档。

安装完成后，即使知识服务暂时离线，项目也应能按本地版本继续工作。