From eb75036b6429932155d0913617cfe03dbbafbcc3 Mon Sep 17 00:00:00 2001 From: csh Date: Fri, 23 Jan 2026 11:37:29 +0800 Subject: [PATCH] :wrench: 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 --- AGENTS.md | 165 +++++++++--------- README.md | 2 +- .../function/11_web_development.md | 4 +- templates/AGENTS.template.md | 18 +- templates/AGENT_RULES.template.md | 22 ++- templates/README.md | 33 +++- .../implementation-plan.template.md | 91 ---------- tests/templates/validate_project_templates.sh | 2 +- 8 files changed, 138 insertions(+), 199 deletions(-) delete mode 100644 templates/memory-bank/implementation-plan.template.md diff --git a/AGENTS.md b/AGENTS.md index c2bf171..30ba4d6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 `$` 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 +- `$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.md（44 行） +2. 触发 $tsl-guide，加载 SKILL.md（192 行） +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.md（44 行） +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.md（44 行） +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？ +A：TSL 非预训练语言，需要从零教学。 -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` diff --git a/README.md b/README.md index 481c69a..4b889f5 100644 --- a/README.md +++ b/README.md @@ -45,7 +45,7 @@ Playbook：TSL（`.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`：执行流程模板 diff --git a/docs/tsl/syntax_book/function/11_web_development.md b/docs/tsl/syntax_book/function/11_web_development.md index 9d22882..b33db96 100644 --- a/docs/tsl/syntax_book/function/11_web_development.md +++ b/docs/tsl/syntax_book/function/11_web_development.md @@ -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） ##### 内容 diff --git a/templates/AGENTS.template.md b/templates/AGENTS.template.md index cbdd374..cb8c917 100644 --- a/templates/AGENTS.template.md +++ b/templates/AGENTS.template.md @@ -1,12 +1,13 @@ -# Agent Instructions +# 代理指引 ## 规则优先级 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/` 下最新计划（如有） --- diff --git a/templates/AGENT_RULES.template.md b/templates/AGENT_RULES.template.md index 22efd57..58a9c30 100644 --- a/templates/AGENT_RULES.template.md +++ b/templates/AGENT_RULES.template.md @@ -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` 记录阻塞原因 diff --git a/templates/README.md b/templates/README.md index f2ba25a..8a1a4e8 100644 --- a/templates/README.md +++ b/templates/README.md @@ -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: + - Parent Plan: + - Verification Scope: local + - Verification Gate: must-pass + +流程： +1) 先完成 brainstorming，并输出设计文档 `docs/plans/YYYY-MM-DD--design.md`。 +2) 询问我“是否进入 `docs/plans/` 实施计划编写阶段”，确认后使用 writing-plans 生成实现计划。 +3) 实现计划内明确标注每步要改的文件与命令；验证步骤只包含可通过的局部验证，不包含测试。 +4) 执行计划并更新 `memory-bank/progress.md`。 +``` ### AGENTS.template.md diff --git a/templates/memory-bank/implementation-plan.template.md b/templates/memory-bank/implementation-plan.template.md deleted file mode 100644 index 34b1780..0000000 --- a/templates/memory-bank/implementation-plan.template.md +++ /dev/null @@ -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}} diff --git a/tests/templates/validate_project_templates.sh b/tests/templates/validate_project_templates.sh index ec0c54c..974aa0d 100644 --- a/tests/templates/validate_project_templates.sh +++ b/tests/templates/validate_project_templates.sh @@ -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