4.0 KiB

Raw Blame History

Agent Instructions (playbook)

About the special nature of the playbook repo:

In the playbook repo: ruleset templates live in rulesets/

In target projects: after sync from playbook, rulesets live in .agents/

AI agents read .agents/ in the target project root (generated by sync_standards.sh)

This document applies to target projects. The playbook repo itself has no source code and does not need AI agent rules.

Use the rules under .agents/ as the source of truth:

Entry: .agents/index.md
Language rules: .agents/tsl/index.md, .agents/cpp/index.md, .agents/python/index.md, .agents/markdown/index.md

Three-layer architecture (layered knowledge base)

This repo organizes agent rules and knowledge into three layers:

Layer 1: `.agents/` (minimal hard rules, <= 50 lines per language)

Load: automatic, always in context
Content: hard constraints and safety red lines
Role: quick decisions on what can or cannot be done
Size control: TSL 44 lines | Python 45 lines | C++ 47 lines | Markdown 31 lines

Layer 2: `codex/skills/` (on-demand, 100-1000 lines per skill)

Load: triggered by $<skill-name> or inferred by the agent
Content: how-to guidance, best practices, workflows
Role: detailed guidance on how to do the task

Key skills:

$tsl-guide - progressive TSL syntax training (basic/advanced/functions/best practices)
$commit-message - commit message convention
$style-cleanup - formatting/style cleanup
$bulk-refactor-workflow - safe bulk refactor workflow

Layer 3: `docs/` (authoritative static docs)

Load: on-demand for specific sections
Content: full language manuals, code style, toolchain config
Role: the final authority
Conflict handling: when rules conflict, follow docs/

Note: the function library is split under docs/tsl/syntax_book/function/. Do not load the whole directory. Load only the needed fragments.

Usage scenarios

Scenario 1: write a simple TSL function

1. Auto read .agents/tsl/index.md (44 lines)
2. Trigger $tsl-guide, load SKILL.md (192 lines)
3. Generate code

Token cost: ~6,000 tokens

Scenario 2: write a TSL class

1. Auto read .agents/tsl/index.md (44 lines)
2. Trigger $tsl-guide, load SKILL.md + references/advanced.md
3. Generate code

Token cost: ~10,000 tokens

Scenario 3: find a TSL function library entry

1. Auto read .agents/tsl/index.md (44 lines)
2. Trigger $tsl-guide, load references/functions_index.md
3. Use rg to locate the function fragment
4. Return the answer

Token cost: ~8,000 tokens

Performance metrics

Metric	Before	Now	Improvement
.agents size	~500 lines	168 lines	-66%
Persistent tokens	~12,500	~4,200	-66%
Avg scenario tokens	~12,500	~10,500	-16%

Maintenance principles

.agents/ modification rules

Do:

Add new security vulnerability types
Update core conventions (file names, format rules)
Add non-negotiable hard constraints

Do not:

Add recommended best practices (put them in a skill)
Add detailed syntax explanations (put them in a skill or docs)
Exceed the 50-line limit (split into skills)

Skills creation rules

Do:

Add new workflows (e.g., code-review)
Teach a new language from scratch (e.g., tsl-guide)
Add cross-language common knowledge (e.g., style-cleanup)

FAQ

Q: Why is .agents/ so small? A: Because it is loaded every conversation. Keeping it under 50 lines saves about 71% of persistent token usage.

Q: Why does TSL need a dedicated tsl-guide skill? A: TSL is not pre-trained. The agent needs from-scratch teaching.

Q: What if my project has custom conventions? A: Fork playbook into the project (git subtree) and modify the project's .agents/.

Skills usage guide: SKILLS.md
Development standards: docs/index.md
Project README: README.md

4.0 KiB Raw Blame History