3.9 KiB

Raw Blame History

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

3.9 KiB Raw Blame History Unescape Escape