147 lines
4.0 KiB
Markdown
147 lines
4.0 KiB
Markdown
# 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
|
|
|
|
```text
|
|
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
|
|
|
|
```text
|
|
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
|
|
|
|
```text
|
|
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/`.
|
|
|
|
---
|
|
|
|
## Related docs
|
|
|
|
- Skills usage guide: `SKILLS.md`
|
|
- Development standards: `docs/index.md`
|
|
- Project README: `README.md`
|