📝 docs(playbook): update prompts and sync notes
This commit is contained in:
parent
60ff3cd035
commit
e23474ef2f
|
|
@ -46,7 +46,7 @@ Playbook：TSL（`.tsl`/`.tsf`）+ C++ + Python + Markdown（代码格式化）
|
|||
`templates/` 目录除了语言配置模板外，还包含 AI 代理工作环境的项目架构模板：
|
||||
|
||||
- `templates/memory-bank/`：项目上下文文档模板（project-brief、tech-stack、architecture、progress、decisions）
|
||||
- `templates/prompts/`：工作流程模板（agent-behavior、clarify、verify）
|
||||
- `templates/prompts/`：工作流程模板（agent-behavior、clarify、review）
|
||||
- `templates/AGENTS.template.md`：路由中心模板（项目主入口）
|
||||
- `templates/AGENT_RULES.template.md`：执行流程模板
|
||||
|
||||
|
|
|
|||
|
|
@ -17,13 +17,16 @@
|
|||
|
||||
[sync_memory_bank]
|
||||
# 同步 memory-bank/（配置节存在即启用）
|
||||
# 只更新框架提供的文件，项目新增的文件不会被删除
|
||||
# ⚠️ force=true 会覆盖已填写的项目信息（自动备份）
|
||||
# project_name = "MyProject" # 可选：替换 {{PROJECT_NAME}}
|
||||
# force = false # 可选：覆盖已有目录（会先备份）
|
||||
# force = false # 可选：覆盖已有文件（会先备份）
|
||||
# no_backup = false # 可选：跳过备份
|
||||
|
||||
[sync_prompts]
|
||||
# 同步 docs/prompts/（配置节存在即启用）
|
||||
# force = false # 可选：覆盖已有目录（会先备份）
|
||||
# 只更新框架提供的文件，项目新增的文件不会被删除
|
||||
# force = false # 可选：覆盖已有文件（会先备份）
|
||||
# no_backup = false # 可选：跳过备份
|
||||
|
||||
[sync_standards]
|
||||
|
|
|
|||
|
|
@ -19,9 +19,11 @@ templates/
|
|||
│ ├── README.md
|
||||
│ ├── system/
|
||||
│ │ └── agent-behavior.template.md
|
||||
│ └── coding/
|
||||
│ ├── clarify.template.md
|
||||
│ └── verify.template.md
|
||||
│ ├── coding/
|
||||
│ │ ├── clarify.template.md
|
||||
│ │ └── review.template.md
|
||||
│ └── meta/
|
||||
│ └── prompt-generator.template.md
|
||||
├── ci/ # CI 模板
|
||||
│ └── gitea/
|
||||
│ └── .gitea/workflows/
|
||||
|
|
@ -35,6 +37,58 @@ templates/
|
|||
└── ...
|
||||
```
|
||||
|
||||
## 文件分类
|
||||
|
||||
从部署角度，文件分为四类：
|
||||
|
||||
| 类型 | 说明 | 部署行为 |
|
||||
|------|------|----------|
|
||||
| **框架模板** | playbook 提供，可随框架升级 | 可覆盖更新 |
|
||||
| **项目上下文** | 首次部署后项目填写 | 首次创建，后续保护 |
|
||||
| **项目私有** | 项目手动创建 | 不部署 |
|
||||
| **参考资料** | 留在 playbook 快照中参考 | 不部署到项目根 |
|
||||
|
||||
### 框架模板（A类）
|
||||
|
||||
```
|
||||
AGENT_RULES.md
|
||||
AGENTS.md（区块更新）
|
||||
docs/prompts/system/*.md # 框架提供
|
||||
docs/prompts/coding/*.md # 框架提供
|
||||
docs/prompts/meta/*.md # 框架提供
|
||||
```
|
||||
|
||||
### 项目上下文（B类）
|
||||
|
||||
```
|
||||
memory-bank/
|
||||
├── project-brief.md
|
||||
├── tech-stack.md
|
||||
├── architecture.md
|
||||
├── progress.md
|
||||
└── decisions.md
|
||||
```
|
||||
|
||||
> ⚠️ B类文件首次创建后应由项目填写。`force=true` 会覆盖已填写内容（自动备份）。
|
||||
|
||||
### 项目私有（C类，不部署）
|
||||
|
||||
```
|
||||
AGENT_RULES.local.md # 项目私有规则
|
||||
docs/plans/ # 项目实施计划
|
||||
docs/prompts/custom/ # 项目自定义提示词
|
||||
docs/prompts/**/* # 项目新增的文件不会被删除
|
||||
```
|
||||
|
||||
### 参考资料（D类，不部署到项目根）
|
||||
|
||||
```
|
||||
# 留在 docs/standards/playbook/templates/ 中参考
|
||||
ci/ # CI 配置
|
||||
cpp/ # C++ 配置
|
||||
python/ # Python 配置
|
||||
```
|
||||
|
||||
## 快速部署
|
||||
|
||||
使用统一入口 `playbook.py`，配置节存在即启用：
|
||||
|
|
@ -74,7 +128,8 @@ python docs/standards/playbook/scripts/playbook.py -config playbook.toml
|
|||
|
||||
- **配置节存在即启用**：只写需要同步的配置节
|
||||
- **AGENTS.md**：始终按区块更新（`<!-- playbook:xxx:start/end -->`），不受配置节控制
|
||||
- **force**：默认 false，已存在则跳过；设为 true 时强制覆盖（memory-bank/ 和 prompts/ 会先备份）
|
||||
- **force**：默认 false，已存在则跳过；设为 true 时覆盖框架文件（会先备份）
|
||||
- **不删除项目文件**：只更新框架提供的文件，项目新增的文件不会被删除
|
||||
- **占位符替换**：自动替换 `{{DATE}}`、`{{PLAYBOOK_SCRIPTS}}` 等
|
||||
|
||||
### 典型场景
|
||||
|
|
@ -112,9 +167,10 @@ project/
|
|||
└── docs/prompts/ # 提示词库
|
||||
├── README.md
|
||||
├── system/agent-behavior.md
|
||||
└── coding/
|
||||
├── clarify.md
|
||||
└── verify.md
|
||||
├── coding/
|
||||
│ ├── clarify.md
|
||||
│ └── review.md
|
||||
└── meta/prompt-generator.md
|
||||
```
|
||||
|
||||
## 占位符说明
|
||||
|
|
@ -151,21 +207,22 @@ project/
|
|||
|
||||
### prompts/
|
||||
|
||||
工作流程模板：
|
||||
工作流程模板（部署后去掉 `.template` 后缀）：
|
||||
|
||||
| 文件 | 用途 |
|
||||
| ----------------------------------- | ------------ |
|
||||
| `system/agent-behavior.template.md` | AI 行为规范 |
|
||||
| `coding/clarify.template.md` | 需求澄清模板 |
|
||||
| `coding/verify.template.md` | 验证检查清单 |
|
||||
| 文件 | 用途 | 使用场景 |
|
||||
| ----------------------------------- | -------------- | ---------------------- |
|
||||
| `system/agent-behavior.template.md` | 工作模式参考 | 切换探索/开发/调试模式 |
|
||||
| `coding/clarify.template.md` | 需求澄清模板 | 需求不明确时 |
|
||||
| `coding/review.template.md` | 复盘总结模板 | Plan 完成后复盘 |
|
||||
| `meta/prompt-generator.template.md` | 元提示词生成器 | 创建新的专用提示词 |
|
||||
|
||||
### AGENT_RULES.template.md
|
||||
|
||||
执行流程规范，定义 AI 的工作循环和约束。
|
||||
如需项目私有规则，建议创建 `AGENT_RULES.local.md`，其优先级高于 `AGENT_RULES.md`，
|
||||
且不会被 `playbook.py` 覆盖。
|
||||
主循环会根据 `memory-bank/progress.md` 的 Plan 状态与 `docs/plans/` 文件名日期，
|
||||
自动选择最新未完成的 Plan，并要求通过 `scripts/plan_progress.py` 写入进度。
|
||||
主循环会根据 `memory-bank/progress.md` 的 Plan 状态清单，
|
||||
自动选择第一个 pending 的 Plan，并要求通过 `scripts/plan_progress.py` 写入状态。
|
||||
|
||||
### 示例：不跑测试的计划提示词
|
||||
|
||||
|
|
|
|||
|
|
@ -11,6 +11,8 @@ tests/
|
|||
│ └── test_playbook_cli.py # playbook.py 基础功能测试
|
||||
├── test_format_md_action.py # format_md 动作测试
|
||||
├── test_gitattributes_modes.py # gitattr_mode 行为测试
|
||||
├── test_sync_directory_actions.py # sync_memory_bank/sync_prompts 行为测试
|
||||
├── test_vendor_snapshot_templates.py # vendor 快照模板完整性测试
|
||||
├── test_plan_progress_cli.py # plan_progress CLI 测试
|
||||
├── test_superpowers_list_sync.py # superpowers 列表一致性测试
|
||||
├── test_sync_templates_placeholders.py # 占位符替换测试（sync_rules/sync_standards）
|
||||
|
|
|
|||
Loading…
Reference in New Issue