peri: Skill for Claude Code

Codebase Index

索引是什么

• 位置：docs/code-index/<crate>.md，跨模块链路在 docs/code-index/cross-crate.md
• 本质：行为 → 文件 的速查表。查询者带着「我想改 X 的 Y」进来，带着文件路径和入口函数出去
• 原则：只给定位信息 + 一句话关键逻辑；不解释原理、不复制规范正文、不替代设计文档
• 体积：每个文件 100–200 行，全部读入没有负担。索引存在的意义就是让"找文件"这一步从几十次搜索变成一次读表

查找流程（查询者视角，最常用）

1. 判断行为落在哪个 crate；不确定就 Glob docs/code-index/*.md 并全部读入
2. 在速查表里按行为关键词匹配条目（compact / keepgoing / is_direct / cancel / middleware / prompt …）
3. 打开主文件，跳转到入口函数
4. 索引里的一句话关键逻辑只用于导航；行为细节一律以代码为准
5. 跨模块链路看各索引的「跨模块契约」节或 cross-crate.md，那里指向 docs/standards/architecture-contracts.md 的 ARC 编号（不复制正文）

构建/更新流程（构建者视角）

触发时机：索引缺失、行为变更后索引过期、用户要求重建/扩充。

输入：目标 crate 源码 + 该 crate 的 CLAUDE.md + docs/standards/architecture-contracts.md（跨模块契约）+ 相关 docs/design/ 文档 + spec/issues/ 中最近的相关 issue。

步骤：

1. 读 crate 的 CLAUDE.md，Scope / 数据流 / 稳定不变量直接进「架构速览」
2. 用 Grep 验证每个文件路径、函数名、常量真实存在（记行号）；禁止凭记忆写路径
3. 逐子系统列条目；每条覆盖：功能 | 文件 | 入口/关键函数 | 一句话关键逻辑
4. 关键逻辑写行为契约（阈值、顺序、条件、边界），一句话讲清，不复制文档正文
5. 标注事实源关系：re-export / 配置事实源 / 注册面要写清归属（例：compact_v2/config.rs 仅 re-export peri-acp-types::compact::CompactConfig，注册面是 middleware collect_tools() 而非工具模块本体）
6. doc comment 与代码不一致时以代码为准（本仓库出现过 mod.rs 顶部 doc 描述的触发语义与实际判断条件不符），并在索引里写实际行为
7. 跨 crate 链路（事件、cancel、工具可见性、prompt frozen 等）进「跨模块契约」节，指向 ARC 编号；涉及多个 crate 的链路同时在相关 crate 的索引里互相可见
8. TUI / UI 类 crate 额外列「关键控件/组件」表（kit 组件、widget 等）
9. 自检：每条路径存在、函数名存在、行为描述与代码一致

索引文件格式（当前 canonical，经两轮检索实验验证）

# <crate> 代码索引

> 速查表：把「我想做什么」映射到文件。细节以代码为准。更新：YYYY-MM-DD
> 依据：<crate>/CLAUDE.md、docs/standards/architecture-contracts.md、源码

## 架构速览
- 数据流 / 循环入口 / 稳定不变量（来自 crate CLAUDE.md）

## 速查表
| 我想做什么 | 主文件 | 入口/关键函数 | 关键逻辑 |
| --- | --- | --- | --- |
| （行为/修改意图，如"改 compact 触发阈值"） | （路径；事实源/re-export 关系标清） | （真实函数名 + 行号） | （一句话行为契约：阈值/顺序/条件） |

## 子系统
### <子系统名>
| 功能 | 文件 | 入口/关键点 |
| --- | --- | --- |

## 跨模块契约
- ARC-XXX-001：一句话要点 → `docs/standards/architecture-contracts.md`

实验结论（为什么是这个结构）：

• 「我想做什么」列直接匹配查询意图，subagent 检索时零推理成本命中（variant-b 模块卡片也准确但需自行提取，效率等价、推理略多）
• 每行带真实入口函数名 + 行号，检索者打开文件即可跳转，不必再全库搜函数
• 一句话行为契约（阈值/顺序/条件）让检索者先判断"这是不是我改的点"，再读代码
• 「跨模块契约」节 + ARC 编号指针足以支撑跨 crate 查询（事件链路等），无需复制契约正文
• 索引错误会被"以代码为准"验证兜住，但构建时写对（标注 re-export/事实源关系、doc 与代码冲突时信代码）能避免误导