# 代理指引（playbook）

> 关于 playbook 仓库的特殊性：
>
> - 在 playbook 仓库中：规则集模板位于 `rulesets/`
> - 在目标项目中：同步后规则集位于 `.agents/`
> - AI 代理读取目标项目根目录的 `.agents/`（由 playbook.py 的 `[sync_standards]` 生成）
>
> 本文适用于目标项目。playbook 仓库自身没有源代码，不需要 AI 代理规则。

以 `.agents/` 下规则为准：

- 入口：`.agents/index.md`
- 语言规则：`.agents/tsl/index.md`、`.agents/cpp/index.md`、
  `.agents/python/index.md`、`.agents/markdown/index.md`

---

## 三层架构（分层知识库）

本仓库将代理规则与知识分为三层：

### Layer 1: `.agents/`（最小硬规则，每种语言 ≤ 50 行）

- 加载：自动，始终在上下文中
- 内容：硬约束与安全红线
- 作用：快速判断能做/不能做
- 规模控制：TSL 44 行 | Python 45 行 | C++ 47 行 | Markdown 31 行

### Layer 2: `codex/skills/`（按需加载，每个 skill 100-1000 行）

- 加载：由 `$<skill-name>` 触发或由代理判定
- 内容：操作指南、最佳实践、工作流
- 作用：指导具体怎么做

关键技能：

- `$tsl-guide` - TSL 渐进式语法训练（基础/高级/函数/最佳实践）
- `$commit-message` - 提交信息规范
- `$style-cleanup` - 格式与风格整理
- `$bulk-refactor-workflow` - 安全批量重构流程

### Layer 3: `docs/`（权威静态文档）

- 加载：按需读取特定章节
- 内容：完整语言手册、代码风格、工具链配置
- 作用：最终权威
- 冲突处理：规则冲突时以 `docs/` 为准

注：函数库拆分在 `docs/tsl/syntax_book/function/` 下。
不要加载整个目录，只加载需要的片段。

---

## 使用场景

### 场景 1：编写简单的 TSL 函数

```text
1. 自动读取 .agents/tsl/index.md（44 行）
2. 触发 $tsl-guide，加载 SKILL.md（192 行）
3. 生成代码

Token 消耗：~6,000 tokens
```

### 场景 2：编写 TSL 类

```text
1. 自动读取 .agents/tsl/index.md（44 行）
2. 触发 $tsl-guide，加载 SKILL.md + references/advanced.md
3. 生成代码

Token 消耗：~10,000 tokens
```

### 场景 3：查询 TSL 函数库条目

```text
1. 自动读取 .agents/tsl/index.md（44 行）
2. 触发 $tsl-guide，加载 references/functions_index.md
3. 使用 rg 定位函数片段
4. 返回答案

Token 消耗：~8,000 tokens
```

---

## 性能指标

| 指标            | 之前    | 现在    | 改善 |
| --------------- | ------- | ------- | ---- |
| .agents 规模    | ~500 行 | 168 行  | -66% |
| 持久化 tokens   | ~12,500 | ~4,200  | -66% |
| 场景平均 tokens | ~12,500 | ~10,500 | -16% |

---

## 维护原则

### .agents/ 修改规则

可做：

- 增加新的安全漏洞类型
- 更新核心约定（文件名、格式规则）
- 添加不可妥协的硬性约束

不可做：

- 添加推荐型最佳实践（放到 skill）
- 添加详细语法解释（放到 skill 或 docs）
- 超过 50 行限制（拆分为 skill）

### Skills 创建规则

可做：

- 增加新流程（如 code-review）
- 从零教授新语言（如 tsl-guide）
- 添加跨语言通用知识（如 style-cleanup）

---

## FAQ

Q：为什么 .agents 这么小？
A：因为它会在每次对话加载。控制在 50 行内可减少约 71% 的持久 token 消耗。

Q：为什么 TSL 需要专门的 tsl-guide？
A：TSL 非预训练语言，需要从零教学。

Q：如果项目有自定义约定怎么办？
A：将 playbook 以 git subtree 方式引入项目，并修改项目的 `.agents/`。

---

## 相关文档

- Skills 使用指南：`SKILLS.md`
- 开发规范：`docs/index.md`
- 项目 README：`README.md`