🔧 chore(templates): align agent templates and docs

- drop implementation-plan template and references
- add AGENT_RULES.local.md precedence in templates
- add plan meta guidance and CN updates
This commit is contained in:
csh 2026-01-23 11:37:29 +08:00
parent efb93f14c1
commit eb75036b64
8 changed files with 138 additions and 199 deletions

165
AGENTS.md
View File

@ -1,146 +1,143 @@
# Agent Instructions (playbook)
# 代理指引playbook
> About the special nature of the playbook repo:
> 关于 playbook 仓库的特殊性:
>
> - 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)
> - 在 playbook 仓库中:规则集模板位于 `rulesets/`
> - 在目标项目中:同步后规则集位于 `.agents/`
> - AI 代理读取目标项目根目录的 `.agents/`(由 sync_standards.sh 生成)
>
> This document applies to target projects. The playbook repo itself has no
> source code and does not need AI agent rules.
> 本文适用于目标项目。playbook 仓库自身没有源代码,不需要 AI 代理规则。
Use the rules under `.agents/` as the source of truth:
`.agents/` 下规则为准:
- Entry: `.agents/index.md`
- Language rules: `.agents/tsl/index.md`, `.agents/cpp/index.md`,
`.agents/python/index.md`, `.agents/markdown/index.md`
- 入口:`.agents/index.md`
- 语言规则:`.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)
### Layer 1: `.agents/`(最小硬规则,每种语言 ≤ 50 行)
- 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
- 加载:自动,始终在上下文中
- 内容:硬约束与安全红线
- 作用:快速判断能做/不能做
- 规模控制TSL 44 行 | Python 45 行 | C++ 47 行 | Markdown 31 行
### Layer 2: `codex/skills/` (on-demand, 100-1000 lines per skill)
### Layer 2: `codex/skills/`(按需加载,每个 skill 100-1000 行)
- 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
- 加载:由 `$<skill-name>` 触发或由代理判定
- 内容:操作指南、最佳实践、工作流
- 作用:指导具体怎么做
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
- `$tsl-guide` - TSL 渐进式语法训练(基础/高级/函数/最佳实践)
- `$commit-message` - 提交信息规范
- `$style-cleanup` - 格式与风格整理
- `$bulk-refactor-workflow` - 安全批量重构流程
### Layer 3: `docs/` (authoritative static docs)
### Layer 3: `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/`
- 加载:按需读取特定章节
- 内容:完整语言手册、代码风格、工具链配置
- 作用:最终权威
- 冲突处理:规则冲突时以 `docs/` 为准
Note: the function library is split under `docs/tsl/syntax_book/function/`.
Do not load the whole directory. Load only the needed fragments.
注:函数库拆分在 `docs/tsl/syntax_book/function/` 下。
不要加载整个目录,只加载需要的片段。
---
## Usage scenarios
## 使用场景
### Scenario 1: write a simple TSL function
### 场景 1编写简单的 TSL 函数
```text
1. Auto read .agents/tsl/index.md (44 lines)
2. Trigger $tsl-guide, load SKILL.md (192 lines)
3. Generate code
1. 自动读取 .agents/tsl/index.md44 行)
2. 触发 $tsl-guide加载 SKILL.md192 行)
3. 生成代码
Token cost: ~6,000 tokens
Token 消耗:~6,000 tokens
```
### Scenario 2: write a TSL class
### 场景 2编写 TSL 类
```text
1. Auto read .agents/tsl/index.md (44 lines)
2. Trigger $tsl-guide, load SKILL.md + references/advanced.md
3. Generate code
1. 自动读取 .agents/tsl/index.md44 行)
2. 触发 $tsl-guide加载 SKILL.md + references/advanced.md
3. 生成代码
Token cost: ~10,000 tokens
Token 消耗:~10,000 tokens
```
### Scenario 3: find a TSL function library entry
### 场景 3查询 TSL 函数库条目
```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
1. 自动读取 .agents/tsl/index.md44 行)
2. 触发 $tsl-guide加载 references/functions_index.md
3. 使用 rg 定位函数片段
4. 返回答案
Token cost: ~8,000 tokens
Token 消耗:~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% |
| 指标 | 之前 | 现在 | 改善 |
| --------------- | -------- | -------- | ---- |
| .agents 规模 | ~500 行 | 168 行 | -66% |
| 持久化 tokens | ~12,500 | ~4,200 | -66% |
| 场景平均 tokens | ~12,500 | ~10,500 | -16% |
---
## Maintenance principles
## 维护原则
### .agents/ modification rules
### .agents/ 修改规则
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)
- 添加推荐型最佳实践(放到 skill
- 添加详细语法解释(放到 skill 或 docs
- 超过 50 行限制(拆分为 skill
### Skills creation rules
### Skills 创建规则
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)
- 增加新流程(如 code-review
- 从零教授新语言(如 tsl-guide
- 添加跨语言通用知识(如 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为什么 .agents 这么小?
A因为它会在每次对话加载。控制在 50 行内可减少约 71% 的持久 token 消耗。
Q: Why does TSL need a dedicated tsl-guide skill?
A: TSL is not pre-trained. The agent needs from-scratch teaching.
Q:为什么 TSL 需要专门的 tsl-guide
ATSL 非预训练语言,需要从零教学。
Q: What if my project has custom conventions?
A: Fork playbook into the project (git subtree) and modify the project's
`.agents/`.
Q如果项目有自定义约定怎么办
A将 playbook 以 git subtree 方式引入项目,并修改项目的 `.agents/`
---
## Related docs
## 相关文档
- Skills usage guide: `SKILLS.md`
- Development standards: `docs/index.md`
- Project README: `README.md`
- Skills 使用指南:`SKILLS.md`
- 开发规范:`docs/index.md`
- 项目 README`README.md`

View File

@ -45,7 +45,7 @@ PlaybookTSL`.tsl`/`.tsf`+ C++ + Python + Markdown代码格式化
`templates/` 目录除了语言配置模板外,还包含 AI 代理工作环境的项目架构模板:
- `templates/memory-bank/`项目上下文文档模板project-brief、tech-stack、architecture、progress、decisions、implementation-plan
- `templates/memory-bank/`项目上下文文档模板project-brief、tech-stack、architecture、progress、decisions
- `templates/prompts/`工作流程模板agent-behavior、clarify、verify
- `templates/AGENTS.template.md`:路由中心模板(项目主入口)
- `templates/AGENT_RULES.template.md`:执行流程模板

View File

@ -3,7 +3,7 @@
#### 内容
- TSL的Web支持
- .Web Tools
- Web 工具(.Web Tools
#### TSL的Web支持
@ -289,7 +289,7 @@ http://www.webiste.com/foo.tsl?name=jack&email=jack@abc.com
可以用上面的方式提取数据
#### .Web Tools
#### Web 工具(.Web Tools
##### 内容

View File

@ -1,12 +1,13 @@
# Agent Instructions
# 代理指引
<!-- playbook:framework:start -->
## 规则优先级
1. 系统/开发者指令与安全约束
2. 仓库规则:`.agents/` 与本文件
3. `AGENT_RULES.md` - 执行流程
2. 项目私有规则:`AGENT_RULES.local.md`(如存在)
3. 仓库规则:`.agents/` 与本文件
4. `AGENT_RULES.md` - 执行流程
---
@ -24,6 +25,7 @@
### 核心规则
- **项目私有规则**[AGENT_RULES.local.md](./AGENT_RULES.local.md)
- **执行流程**[AGENT_RULES.md](./AGENT_RULES.md)
- **AI 行为规范**[docs/prompts/system/agent-behavior.md](docs/prompts/system/agent-behavior.md)
@ -34,7 +36,6 @@
- **架构设计**[memory-bank/architecture.md](memory-bank/architecture.md)
- **进度追踪**[memory-bank/progress.md](memory-bank/progress.md)
- **架构决策**[memory-bank/decisions.md](memory-bank/decisions.md)
- **实施计划**[memory-bank/implementation-plan.md](memory-bank/implementation-plan.md)
### 工作流程
@ -48,10 +49,11 @@
**AI 应该做的**
1. 读取 [AGENT_RULES.md](./AGENT_RULES.md)
2. 读取 [memory-bank/](memory-bank/) 核心文档
3. 读取 [docs/prompts/system/agent-behavior.md](docs/prompts/system/agent-behavior.md)
4. 查看 `docs/plans/` 下最新计划(如有)或 `memory-bank/implementation-plan.md`
1. 读取 [AGENT_RULES.local.md](./AGENT_RULES.local.md)(如存在)
2. 读取 [AGENT_RULES.md](./AGENT_RULES.md)
3. 读取 [memory-bank/](memory-bank/) 核心文档
4. 读取 [docs/prompts/system/agent-behavior.md](docs/prompts/system/agent-behavior.md)
5. 查看 `docs/plans/` 下最新计划(如有)
<!-- playbook:framework:end -->
---

View File

@ -5,18 +5,19 @@
## 优先级
1. 系统/开发者指令与安全约束
2. 仓库规则:`.agents/` 与 `AGENTS.md`
3. 本文件
2. 项目私有规则:`AGENT_RULES.local.md`(如存在)
3. 仓库规则:`.agents/` 与 `AGENTS.md`
4. 本文件
## 上下文加载(每次会话开始)
**必读文档**(按顺序):
1. `memory-bank/project-brief.md` - 项目定位、边界、约束
2. `memory-bank/tech-stack.md` - 技术栈、工具链
3. `memory-bank/architecture.md` - 架构设计、模块职责
4. `docs/plans/` - 最新实施计划(如存在)
5. `memory-bank/implementation-plan.md` - 当前实施计划(如存在)
1. `AGENT_RULES.local.md` - 项目私有规则(如存在,优先级高于本文件)
2. `memory-bank/project-brief.md` - 项目定位、边界、约束
3. `memory-bank/tech-stack.md` - 技术栈、工具链
4. `memory-bank/architecture.md` - 架构设计、模块职责
5. `docs/plans/` - 最新实施计划(如存在)
**目的**:让 AI 快速理解项目全貌,避免重复解释。
@ -33,6 +34,13 @@
## Plan 规则
- **Plan Meta 必填**Plan 头部 `---` 之后、Task 1 之前插入 `## Plan Meta`,包含:
- `Plan Group`(归类任务)
- `Parent Plan`(上层/集成计划链接)
- `Verification Scope`local 或 integration
- `Verification Gate`must-pass
- **不允许中断任务**Plan 中不应包含必然失败或依赖未确认的信息;未确认项必须在 brainstorming 阶段解决后再产出 Plan
- **验证必须可通过**Plan 内验证应为当前阶段可通过的局部验证;需要集成验证的内容放入上层/集成 Plan
- 不因等待确认而中断可执行步骤;待确认事项在回复中列出
- 执行并验证该 Plan 中所有可执行的子任务
- 若因缺少信息/决策而阻塞:在 `memory-bank/progress.md` 记录阻塞原因

View File

@ -14,8 +14,7 @@ templates/
│ ├── tech-stack.template.md
│ ├── architecture.template.md
│ ├── progress.template.md
│ ├── decisions.template.md
│ └── implementation-plan.template.md
│ └── decisions.template.md
├── prompts/ # 提示词库模板
│ ├── README.md
│ ├── system/
@ -82,13 +81,13 @@ scripts\sync_templates.bat -project-root C:\path\to\project -full
project/
├── AGENTS.md # 路由中心(主入口)
├── AGENT_RULES.md # 执行流程
├── AGENT_RULES.local.md # 项目私有规则(可选,手动维护)
├── memory-bank/ # 项目上下文
│ ├── project-brief.md
│ ├── tech-stack.md
│ ├── architecture.md
│ ├── progress.md
│ ├── decisions.md
│ └── implementation-plan.md
│ └── decisions.md
└── docs/prompts/ # 提示词库
├── README.md
├── system/agent-behavior.md
@ -123,7 +122,6 @@ project/
| `architecture.template.md` | 架构设计、模块职责 |
| `progress.template.md` | 开发进度追踪 |
| `decisions.template.md` | 架构决策记录ADR |
| `implementation-plan.template.md` | 当前实施计划 |
### prompts/
@ -138,6 +136,31 @@ project/
### AGENT_RULES.template.md
执行流程规范,定义 AI 的工作循环和约束。
如需项目私有规则,建议创建 `AGENT_RULES.local.md`,其优先级高于 `AGENT_RULES.md`
且不会被同步脚本覆盖。
### 示例:不跑测试的计划提示词
当你需要修改代码但暂时不运行测试时,可用以下提示词生成“可执行且不失败”的实施计划:
```text
你是 Codex。先使用 $brainstorming。
目标:修改 <模块/功能>,细节如下:<你的需求>
约束:
- 不跑任何测试test/ci但允许做可通过的局部验证格式化/静态检查/人工 diff
- Plan 不能包含任何必然失败或未确认的任务;所有依赖必须在 brainstorming 阶段确认清楚。
- 采用 writing-plans 的固定头部格式,且在 `---` 之后追加 `## Plan Meta`
- Plan Group: <X>
- Parent Plan: <docs/plans/...-design.md>
- Verification Scope: local
- Verification Gate: must-pass
流程:
1) 先完成 brainstorming并输出设计文档 `docs/plans/YYYY-MM-DD-<topic>-design.md`
2) 询问我“是否进入 `docs/plans/` 实施计划编写阶段”,确认后使用 writing-plans 生成实现计划。
3) 实现计划内明确标注每步要改的文件与命令;验证步骤只包含可通过的局部验证,不包含测试。
4) 执行计划并更新 `memory-bank/progress.md`
```
### AGENTS.template.md

View File

@ -1,91 +0,0 @@
# 当前实施计划
## 计划状态
**计划名称**: {{PLAN_NAME}}
**开始时间**: {{START_DATE}}
**当前状态**: 进行中 / 已完成 / 已暂停
---
## 目标
{{PLAN_GOAL}}
**成功标准**:
- [ ] {{SUCCESS_CRITERIA_1}}
- [ ] {{SUCCESS_CRITERIA_2}}
- [ ] {{SUCCESS_CRITERIA_3}}
---
## 实施步骤
### 阶段 1: {{PHASE_1_NAME}}
#### 步骤 1.1: {{STEP_1_1}}
- [ ] {{TASK_1_1_1}}
- [ ] {{TASK_1_1_2}}
**验证**: {{VERIFICATION_1_1}}
#### 步骤 1.2: {{STEP_1_2}}
- [ ] {{TASK_1_2_1}}
- [ ] {{TASK_1_2_2}}
**验证**: {{VERIFICATION_1_2}}
---
### 阶段 2: {{PHASE_2_NAME}}
#### 步骤 2.1: {{STEP_2_1}}
- [ ] {{TASK_2_1_1}}
- [ ] {{TASK_2_1_2}}
**验证**: {{VERIFICATION_2_1}}
---
## 当前进度
### 已完成
- {{COMPLETED_PHASE}}
### 进行中
- {{IN_PROGRESS_STEP}}
### 待开始
- {{PENDING_STEP}}
---
## 风险与问题
### 风险
1. **{{RISK_1}}**
- 风险:{{RISK_1_DESC}}
- 缓解:{{RISK_1_MITIGATION}}
### 已解决的问题
1. {{RESOLVED_ISSUE_1}}
---
## 下一步行动
- [ ] {{NEXT_ACTION_1}}
- [ ] {{NEXT_ACTION_2}}
---
**最后更新**{{DATE}}

View File

@ -79,7 +79,7 @@ echo ""
echo "🔍 验证 memory-bank 模板"
MEMORY_BANK_DIR="$TEMPLATES_DIR/memory-bank"
for name in project-brief tech-stack architecture progress decisions implementation-plan; do
for name in project-brief tech-stack architecture progress decisions; do
validate_file_exists "$MEMORY_BANK_DIR/$name.template.md" "memory-bank/$name.template.md"
done