# CLAUDE.md 注入规则

`eo-doc-manager` 的 `init` 会向项目根目录的 agent 配置文件注入文档体系说明，让 AI 在每次会话启动时知道 `eo-doc/` 的结构。

`eo-project-init` 另外注入 `<!-- eo-project:start -->`（项目管理侧说明）与 `<!-- eo-reply-contract:start -->`（长任务收尾回复契约）两个段落，三者互不干扰。

## 注入标记

```markdown
<!-- eo-doc:start -->
...（注入内容）...
<!-- eo-doc:end -->
```

## 注入模板

```markdown
<!-- eo-doc:start -->
## eo-doc 文档体系（代码侧）

代码侧文档根目录 `eo-doc/`。

| 目录 | 用途 | 何时读 |
|------|------|--------|
| [changes/](eo-doc/changes/INDEX.md) | change 工件流（change/review/test） | 查变更进度 |
| [agent-handbook/](eo-doc/agent-handbook/INDEX.md) | 项目操作手册（commit/注释/worktree/架构/目录/UI 规范） | 做对应操作前读对应篇；不存在则无此约束 |
| [templates/](eo-doc/templates/) | 项目定制模板（eo-* 技能扩展点） | eo-* 技能启动时自动读取 |
> **注释纪律（硬入口）**：编辑任何代码前，`eo-doc/agent-handbook/comments.md` 存在则必读并遵循——它约束一切代码改动，含不经 eo 流程的直改。

> 项目管理侧（roadmap / decisions / lessons / 原始 PRD 与设计）见 `.eo-project.json`（同目录如有 `.eo-project.local.json` 则字段覆盖，local 优先）的 `project_root` 字段。
<!-- eo-doc:end -->
```

## 注入流程

### 场景 1：CLAUDE.md 不存在

1. 在项目根目录创建 CLAUDE.md
2. 写入：
   ```markdown
   # CLAUDE.md

   本文档为 AI Agent 提供项目全局上下文。

   <!-- eo-doc:start -->
   ...（注入模板）...
   <!-- eo-doc:end -->
   ```

### 场景 2：CLAUDE.md 存在，无 `<!-- eo-doc:start -->` 标记

1. 读取现有 CLAUDE.md 全文
2. 按封闭选择协议（[../../eo-shared/questioning.md](../../eo-shared/questioning.md) §4）问：注入到文件末尾（推荐）or 用户指定位置
3. 默认追加到文件末尾（保持两空行间隔）
4. 添加 `<!-- eo-doc:start -->` / `<!-- eo-doc:end -->` 标记包裹注入内容

### 场景 3：CLAUDE.md 存在，已有 `<!-- eo-doc:start -->` 标记

1. 定位 `<!-- eo-doc:start -->` 到 `<!-- eo-doc:end -->` 之间的内容
2. **完全替换**为新的注入模板（不做局部 merge）
3. 保留标记外的其他内容不变

## 验证

注入完成后：
- [ ] CLAUDE.md 存在且可读
- [ ] `<!-- eo-doc:start -->` 和 `<!-- eo-doc:end -->` 成对出现
- [ ] 表格渲染正常（列数一致）
- [ ] 所有链接指向真实存在的目录/INDEX.md

# INDEX.md 模板

`eo-doc/` 下**无顶级 INDEX.md**（CLAUDE.md 里的目录表即是一级索引）；每个子目录各自维护自己的 INDEX.md 作为二级索引。

## 目录级 INDEX.md

```markdown
# [分类名] Index

> Last updated: YYYY-MM-DD
> Total: N docs

| File | Title | Tags | Updated | Summary |
|------|-------|------|---------|---------|
| [filename.md](filename.md) | 标题 | `tag1` `tag2` | YYYY-MM-DD | 一句摘要 |
```

> `changes/INDEX.md` 使用上面的标准列。

## 分组式 INDEX（10+ 篇时使用）

```markdown
# [分类名] Index

> Last updated: YYYY-MM-DD
> Total: N docs

## [子分类 A]

| File | Title | Tags | Updated | Summary |
|------|-------|------|---------|---------|
| [file1.md](file1.md) | 标题 | `tag` | YYYY-MM-DD | 摘要 |

## [子分类 B]

| File | Title | Tags | Updated | Summary |
|------|-------|------|---------|---------|
| [file2.md](file2.md) | 标题 | `tag` | YYYY-MM-DD | 摘要 |

## 已归档

| File | Title | Archived | Replacement |
|------|-------|----------|-------------|
| [old.md](old.md) | 旧版本 | YYYY-MM-DD | [new.md](new.md) |
```

## 维护规则

- 每次新增/修改/归档文档后，**同步更新受影响目录的 INDEX.md**
- 摘要列与文档 frontmatter 的 `summary` 字段保持一致
- 标签列与 frontmatter 的 `tags` 字段保持一致
- 按 `updated` 倒序排列（最近更新的在前）
- 单条目约 50 token，整个 INDEX 可一次性扫描

# 维护协议

## changes/INDEX.md 整理

1. 列出 `changes/` 下全部子目录，与 INDEX.md 条目比对：
   - 孤儿条目（指向已删除目录）→ 删除该行
   - 漏收目录 → 读其 change.md frontmatter 补行
2. 状态/摘要列与各 change.md frontmatter 保持一致（以 frontmatter 为准）
3. seq 列顺手查重：重号 → created 晚者让号（见 [../../eo-shared/conventions.md](../../eo-shared/conventions.md) §2）
4. 单条目保持约 50 token，整个 INDEX 可一次性扫描

## templates/ 管理

- 模板由项目按需自建（如项目类型画像 `project-profile.md`），本 skill 不自动生成内容
- 模板内容完全来自用户输入；templates/ 无 INDEX，无需同步索引

## 验证

- [ ] INDEX 条目与目录一一对应
- [ ] 所有交叉引用指向真实存在的文件

# Mermaid 图规范（eo-skills 统一约定）

本规范覆盖 eo-skills 体系内所有 mermaid 图的类型选择、样式约定、维护规则。

主要消费方：
- `eo-change` — 条件节 §6 流程图（画比说清楚时才画）
- `eo-recall` — 回忆问答的按需出图
- `eo-change-review` — change 含 §6 流程图时按本文件 §5 审查清单核对

## 1. 图类型选择矩阵

| 目标 | 图类型 | 用在哪 |
|------|--------|--------|
| 用户操作流程、业务决策分支 | `flowchart TD` | change §6、recall 输出 |
| 多角色/多系统交互、时序敏感 | `sequenceDiagram` | change §6（涉及跨系统调用） |
| 业务状态机、生命周期 | `stateDiagram-v2` | change §6、recall 输出 |
| 组件/依赖关系 | `flowchart LR/TB` | recall 输出 |

**选型原则**：能用 `flowchart` 表达就不要上 `sequenceDiagram`；用户读图的认知成本低于语法表达力。

## 2. classDef 规范（change 流程图专用）

change.md 的流程图画的是**变更后的完整流程**，不是 diff。但要用 classDef 高亮这次 change 动了哪些节点，方便审查者一眼抓差异。

### 固定 classDef 定义

每张 change 流程图末尾必须包含这三行（无论有没有用到）：

```
classDef new fill:#d4edda,stroke:#28a745,stroke-width:2px
classDef changed fill:#fff3cd,stroke:#ffc107,stroke-width:2px
classDef extern fill:#e9ecef,stroke:#6c757d,stroke-dasharray:5 5
```

### 应用规则

| 场景 | 写法 |
|------|------|
| 本 change 新增的节点 | `NodeId:::new` |
| 本 change 修改了语义/行为的节点 | `NodeId:::changed` |
| 依赖的外部模块节点（非本模块内部） | `NodeId:::extern` |
| 本 change 删除的节点 | **不画在图里**，在图下方用 `> 移除：<原节点名> —— <原因>` 说明 |

### 归档后的去向

流程图随 change 目录一起归档冻结，**无任何合并动作**；`:::new` / `:::changed` 标注原样保留——它们是该次变更的历史痕迹。

## 3. 命名规则

- **节点 ID**：英文 kebab / camelCase，短（`validate-input`、`checkStock`），不要中文或空格
- **节点 label**：中文，简洁动词短语（`[验证输入]`、`{库存足够?}`）
- **决策节点**：菱形 `{...}`，label 末尾带 `?`
- **子图（subgraph）**：仅在一张图 ≥ 15 个节点时才用，用来分组

## 4. 最小示例

### 示例 A — 业务状态机（示意：某审核流的领域状态）

```mermaid
stateDiagram-v2
    [*] --> draft
    draft --> pending: 提交审核
    pending --> approved: 审核通过
    pending --> draft: 审核驳回
    approved --> archived: 归档
    archived --> [*]
```

### 示例 B — change §6 流程图（带变更高亮）

```mermaid
flowchart TD
    Start([用户发起下单]) --> ValidateUser[校验用户资质]
    ValidateUser --> CheckStock{库存充足?}
    CheckStock -->|是| RiskCheck[风控审核]
    CheckStock -->|否| Fail([下单失败])
    RiskCheck --> CreateOrder[创建订单]
    CreateOrder --> NotifyWMS[[通知 WMS 模块]]
    NotifyWMS --> Done([完成])

    RiskCheck:::new
    CheckStock:::changed
    NotifyWMS:::extern

    classDef new fill:#d4edda,stroke:#28a745,stroke-width:2px
    classDef changed fill:#fff3cd,stroke:#ffc107,stroke-width:2px
    classDef extern fill:#e9ecef,stroke:#6c757d,stroke-dasharray:5 5
```

> 移除：原"人工审核"节点 —— 由新增的"风控审核"自动节点替代。

### 示例 C — 项目级模块依赖图

```mermaid
flowchart TB
    subgraph 业务层
        order[订单]
        inventory[库存]
    end
    subgraph 基础层
        user[用户]
        config[配置]
    end
    order --> inventory
    order --> user
    inventory --> config
```

## 5. 审查清单（给 review 类 skill）

| 检查项 | 严重度 |
|--------|--------|
| change 满足 §6 触发条件（状态机/多角色交互）却未画图 | P2 |
| 图与代码实现不一致（节点/分支/状态对不上） | P1 |
| change 流程图有明显变更点却缺 `:::new` / `:::changed` 标注 | P2 |
| 节点 ID 含中文或空格（违反命名规则） | P3 |
| 图类型选错（如用 sequenceDiagram 画纯流程） | P3 |

## 6. 什么时候可以不画

- 纯配置调整、纯文案/样式变更
- 单一能力点新增且不涉及流程分支
- 用文字一句能说清的线性流程

满足 change 模板 §6 触发条件（状态机、多角色交互等「画比说清楚」的场景）才画，其余默认不画。