3.6 KiB

Raw Blame History

代理指引（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 函数

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

Token 消耗：~6,000 tokens

场景 2：编写 TSL 类

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

Token 消耗：~10,000 tokens

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

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/。

3.6 KiB Raw Blame History Unescape Escape