tsl-devkit/templates

项目架构模板

本目录包含项目架构的模板文件，用于快速初始化新项目的 AI 代理工作环境。

目录结构

templates/
├── README.md                    # 本文件
├── AGENTS.template.md           # 路由中心模板
├── AGENT_RULES.template.md      # 执行流程模板
├── memory-bank/                 # 项目上下文模板
│   ├── project-brief.template.md
│   ├── tech-stack.template.md
│   ├── architecture.template.md
│   ├── progress.template.md
│   └── decisions.template.md
├── prompts/                     # 提示词库模板
│   ├── README.md
│   ├── system/
│   │   └── agent-behavior.template.md
│   ├── coding/
│   │   ├── clarify.template.md
│   │   └── review.template.md
│   └── meta/
│       └── prompt-generator.template.md
├── ci/                          # CI 模板
│   └── gitea/
│       └── .gitea/workflows/
├── cpp/                         # C++ 配置模板
│   ├── .clang-format
│   ├── .clangd
│   └── ...
└── python/                      # Python 配置模板
    ├── .editorconfig
    ├── pyproject.toml
    └── ...

文件分类

从部署角度，文件分为四类：

类型	说明	部署行为
框架模板	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，配置节存在即启用：

# playbook.toml
[playbook]
project_root = "/path/to/project"

# 同步 AGENT_RULES.md（配置节存在即启用）
[sync_rules]
# force = true  # 可选，强制覆盖已存在的文件

# 同步 memory-bank/（配置节存在即启用）
[sync_memory_bank]
project_name = "MyProject"
# force = true  # 可选，强制覆盖（会先备份）

# 同步 docs/prompts/（配置节存在即启用）
[sync_prompts]
# force = true  # 可选，强制覆盖（会先备份）

python docs/standards/playbook/scripts/playbook.py -config playbook.toml

参数说明见 playbook.toml.example（仓库根目录）或 vendoring 后的 docs/standards/playbook/playbook.toml.example。

配置节说明

配置节	部署内容	选项
[sync_rules]	AGENT_RULES.md	force
[sync_memory_bank]	memory-bank/	project_name, force
[sync_prompts]	docs/prompts/	force

• 配置节存在即启用：只写需要同步的配置节
• AGENTS.md：始终按区块更新（<!-- playbook:xxx:start/end -->），不受配置节控制
• force：默认 false，已存在则跳过；设为 true 时覆盖框架文件（会先备份）
• 不删除项目文件：只更新框架提供的文件，项目新增的文件不会被删除
• 占位符替换：自动替换 {{DATE}}、{{PLAYBOOK_SCRIPTS}} 等

典型场景

# 场景 1：初次部署（全部）
[sync_rules]
[sync_memory_bank]
project_name = "MyProject"
[sync_prompts]

# 场景 2：框架升级（只更新规则）
[sync_rules]
force = true

# 场景 3：重置项目上下文
[sync_memory_bank]
project_name = "MyProject"
force = true

部署后的目录结构

project/
├── AGENTS.md              # 路由中心（主入口）
├── AGENT_RULES.md         # 执行流程
├── AGENT_RULES.local.md   # 项目私有规则（可选，手动维护）
├── memory-bank/           # 项目上下文
│   ├── project-brief.md
│   ├── tech-stack.md
│   ├── architecture.md
│   ├── progress.md
│   └── decisions.md
└── docs/prompts/          # 提示词库
    ├── README.md
    ├── system/agent-behavior.md
    ├── coding/
    │   ├── clarify.md
    │   └── review.md
    └── meta/prompt-generator.md

占位符说明

模板中使用 {{PLACEHOLDER}} 格式的占位符，需要替换为实际值：

占位符	说明	自动替换
{{DATE}}	日期	✅ 是
{{PROJECT_NAME}}	项目名称	✅ 可选
{{PROJECT_GOAL}}	项目目标	❌ 手动
{{PROJECT_DESCRIPTION}}	项目描述	❌ 手动
{{MAIN_LANGUAGE}}	主语言	✅ 可选
{{PLAYBOOK_SCRIPTS}}	脚本路径	✅ 是
其他 {{...}}	项目特定内容	❌ 手动

{{PROJECT_NAME}} 可通过 sync_memory_bank.project_name 自动替换；未配置时保持原样。 {{MAIN_LANGUAGE}} 可通过 sync_standards.langs[0] 自动替换；未配置时默认 tsl。 {{PLAYBOOK_SCRIPTS}} 自动替换为 Playbook 脚本路径（默认 docs/standards/playbook/scripts）。

模板说明

memory-bank/

项目上下文文档，用于让 AI 快速理解项目：

文件	用途
project-brief.template.md	项目定位、边界、约束
tech-stack.template.md	技术栈、工具链、环境
architecture.template.md	架构设计、模块职责
progress.template.md	开发进度追踪
decisions.template.md	架构决策记录（ADR）

prompts/

工作流程模板（部署后去掉 .template 后缀）：

文件	用途	使用场景
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 状态清单， 自动选择第一个 pending 的 Plan，并要求通过 scripts/plan_progress.py 写入状态。

示例：不跑测试的计划提示词

当你需要修改代码但暂时不运行测试时，可用以下提示词生成“可执行且不失败”的实施计划：

你是 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

路由中心模板，作为项目的主入口。

设计理念：

• 最小化内容：只包含导航链接，不包含详细规则
• 结构化导航：分为核心规则、项目上下文、工作流程三个板块

playbook 标记（用于自动更新）：

标记	用途	说明
<!-- playbook:agents:start/end -->	语言规则链接	由 [sync_standards] 管理
<!-- playbook:templates:start/end -->	路由链接	AGENTS.md 始终按区块更新
<!-- playbook:framework:start/end -->	完整框架	AGENTS.md 始终按区块更新

ci/、cpp/、python/

语言和 CI 配置模板。通过 playbook.py 的 [vendor] 复制到快照中：

目录	内容	部署位置
ci/gitea/	Gitea Actions 工作流	快照 templates/ci/
cpp/	.clang-format, .clangd, CMakeLists.txt 等	快照 templates/cpp/
python/	pyproject.toml, .editorconfig 等	快照 templates/python/

注意：这些模板通过 [vendor] 复制到快照的 templates/ 目录，需手动从快照复制到项目根目录使用。

使用方式：

# playbook.toml - 生成包含这些模板的快照
[playbook]
project_root = "/path/to/project"

[vendor]
langs = ["tsl", "cpp", "python"]

python scripts/playbook.py -config playbook.toml
# 然后手动从 docs/standards/playbook/templates/ 复制所需配置到项目根目录

与 playbook 其他部分的关系

playbook/
├── rulesets/        # 语言级硬规则 → 部署到 .agents/
├── codex/skills/    # 按需加载的技能
├── docs/            # 权威静态文档
├── templates/       # 本目录：项目架构模板 → 部署到 memory-bank/ 等
└── scripts/
    ├── playbook.py        # 统一入口：vendor/sync_rules/sync_memory_bank/sync_prompts/sync_standards/...
    └── plan_progress.py   # Plan 选择与进度记录

完整部署流程

# 1. 准备配置并执行统一入口
python docs/standards/playbook/scripts/playbook.py -config playbook.toml

# 2. 编辑 memory-bank/*.md 填写项目信息

# 3. 替换剩余的 {{PLACEHOLDER}} 占位符

---

最后更新：2026-01-26