# Agent Instructions (playbook)

> **关于 playbook 仓库的特殊性**：
>
> - **在 playbook 仓库中**：规则集模板存储在 `rulesets/` 目录
> - **在目标项目中**：从 playbook 同步后，规则集位于 `.agents/` 目录
> - **AI 代理读取**：目标项目根目录的 `.agents/`（由 sync_standards.sh 生成）
>
> 本文档适用于**目标项目**。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 47 行 | Python 48 行 | C++ 50 行 | Markdown 23 行

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

- **加载方式**：通过 `$<skill-name>` 触发或 Agent 推断
- **内容**：语法教学/最佳实践/工作流程
- **职责**：提供"怎么做"的详细知识

**关键 Skills**：
- `$tsl-guide` - TSL 渐进式语法教学（基础/高级/函数库/最佳实践）
- `$performance-optimization` - 跨语言性能优化工作流
- `$testing-workflow` - 跨语言测试策略
- `$code-review-workflow` - 代码审查流程
- `$commit-message` - 提交信息规范

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

- **加载方式**：按需检索特定章节
- **内容**：完整语法手册/代码风格/工具链配置
- **职责**：最终权威来源
- **冲突处理**：当规则冲突时，以 `docs/` 为准

> **注意**：函数库已拆分在 `docs/tsl/syntax_book/function/`，**禁止整目录加载**，请按需检索片段。

---

## 使用场景示例

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

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

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

### 场景 2：编写 TSL Class

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

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

### 场景 3：查找 TSL 函数库

```
1. 自动读取 .agents/tsl/index.md (47 行)
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）
- ✅ 跨语言通用知识（如 performance-optimization）

---

## FAQ

**Q: 为什么 .agents/ 这么简洁？**
A: 因为会每次对话自动加载，精简到 50 行可节省 71% 持续 token 消耗。

**Q: 为什么 TSL 需要专门的 tsl-guide skill？**
A: TSL 是未被预训练的语言，Agent 零知识，需要"从零教学"。

**Q: 项目有自定义约定怎么办？**
A: Fork playbook 到项目中（git subtree），修改项目根目录的 .agents/。

---

## 相关文档

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