143 lines
4.0 KiB
Markdown
143 lines
4.0 KiB
Markdown
# 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`
|