✨ feat(templates): add sync templates scaffolding
This commit is contained in:
@@ -0,0 +1,60 @@
|
||||
# Agent Instructions
|
||||
|
||||
<!-- playbook:framework:start -->
|
||||
|
||||
## 规则优先级
|
||||
|
||||
1. 系统/开发者指令与安全约束
|
||||
2. 仓库规则：`.agents/` 与本文件
|
||||
3. `AGENT_RULES.md` - 执行流程
|
||||
4. `TODO.md` - 任务队列
|
||||
|
||||
---
|
||||
|
||||
## 快速导航
|
||||
|
||||
<!-- playbook:agents:start -->
|
||||
|
||||
请以 `.agents/` 下的规则为准：
|
||||
|
||||
- 入口：`.agents/index.md`
|
||||
- 语言规则：`.agents/{{MAIN_LANGUAGE}}/index.md`
|
||||
<!-- playbook:agents:end -->
|
||||
|
||||
<!-- playbook:templates:start -->
|
||||
|
||||
### 核心规则
|
||||
|
||||
- **执行流程**：[AGENT_RULES.md](./AGENT_RULES.md)
|
||||
- **AI 行为规范**：[docs/prompts/system/agent-behavior.md](docs/prompts/system/agent-behavior.md)
|
||||
|
||||
### 项目上下文
|
||||
|
||||
- **项目定位**：[memory-bank/project-brief.md](memory-bank/project-brief.md)
|
||||
- **技术栈**：[memory-bank/tech-stack.md](memory-bank/tech-stack.md)
|
||||
- **架构设计**：[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)
|
||||
|
||||
### 工作流程
|
||||
|
||||
- **需求澄清**：[docs/prompts/coding/clarify.md](docs/prompts/coding/clarify.md)
|
||||
- **验证检查**：[docs/prompts/coding/verify.md](docs/prompts/coding/verify.md)
|
||||
<!-- playbook:templates:end -->
|
||||
|
||||
---
|
||||
|
||||
## 新会话开始时
|
||||
|
||||
**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. 查看 [TODO.md](./TODO.md) 和 [CONFIRM.md](./CONFIRM.md)
|
||||
<!-- playbook:framework:end -->
|
||||
|
||||
---
|
||||
|
||||
**最后更新**：{{DATE}}
|
||||
@@ -0,0 +1,81 @@
|
||||
# AGENT_RULES
|
||||
|
||||
目的：为本仓库提供稳定的执行流程。
|
||||
|
||||
## 优先级
|
||||
|
||||
1. 系统/开发者指令与安全约束
|
||||
2. 仓库规则：`.agents/` 与 `AGENTS.md`
|
||||
3. 本文件
|
||||
4. `TODO.md`
|
||||
|
||||
## 上下文加载（每次会话开始）
|
||||
|
||||
**必读文档**（按顺序）：
|
||||
|
||||
1. `memory-bank/project-brief.md` - 项目定位、边界、约束
|
||||
2. `memory-bank/tech-stack.md` - 技术栈、工具链
|
||||
3. `memory-bank/architecture.md` - 架构设计、模块职责
|
||||
4. `TODO.md` - 当前任务队列
|
||||
5. `CONFIRM.md` - 待确认事项
|
||||
|
||||
**目的**：让 AI 快速理解项目全貌，避免重复解释。
|
||||
|
||||
## 主循环
|
||||
|
||||
1. 读取 `TODO.md`
|
||||
2. 选择最上方的 Plan
|
||||
3. **读取 `memory-bank/implementation-plan.md`**（若该 Plan 有对应说明）
|
||||
4. 执行该 Plan 内所有可执行子任务
|
||||
5. 校验输出结果（运行测试/检查日志）
|
||||
6. **更新 `memory-bank/progress.md`**（记录已完成事项）
|
||||
7. 如存在歧义/风险/决策点，记录到 `CONFIRM.md`
|
||||
8. 若 Plan 已全部完成，则从 `TODO.md` 移除
|
||||
9. 若 Plan 因缺少信息而阻塞，标记为 `BLOCKED` 并移到 `TODO.md` 末尾
|
||||
10. 重新读取 `TODO.md`，继续下一个 Plan
|
||||
|
||||
## Plan 规则
|
||||
|
||||
- 不因等待确认而中断；记录到 `CONFIRM.md` 后继续
|
||||
- 执行并验证该 Plan 中所有可执行的子任务
|
||||
- 若因缺少信息/决策而阻塞：记录 `CONFIRM.md`，标记为 `BLOCKED`，移到末尾（不移除）
|
||||
- 每轮只处理一个 Plan
|
||||
- **小步快跑**：每个 Plan 应该可快速完成
|
||||
- **可验证**：每个 Plan 必须包含验证步骤
|
||||
|
||||
## 执行约束
|
||||
|
||||
### 代码修改约束
|
||||
|
||||
- **必须先读文件再修改**：不读文件就提议修改是禁止的
|
||||
- **必须运行测试验证**：相关测试必须通过
|
||||
- **遵循换行规则**：遵循 `.gitattributes` 规则
|
||||
|
||||
### 决策记录约束
|
||||
|
||||
- **重要决策**：记录到 `memory-bank/decisions.md`（ADR 格式）
|
||||
- **临时确认**：记录到 `CONFIRM.md`（会话级）
|
||||
- **进度留痕**：记录到 `memory-bank/progress.md`（持久化）
|
||||
|
||||
## CONFIRM.md 触发条件
|
||||
|
||||
- 需求不明确或存在多种可行方案
|
||||
- 需要行为/兼容性取舍
|
||||
- 风险或约束冲突
|
||||
- **架构变更**：影响多个模块的修改
|
||||
- **性能权衡**：需要在性能和可维护性之间选择
|
||||
- **兼容性问题**：可能破坏现有用户代码
|
||||
|
||||
## 验证清单
|
||||
|
||||
每个 Plan 完成后，必须验证：
|
||||
|
||||
- [ ] 代码修改符合 `.agents/` 下的规则
|
||||
- [ ] 相关测试通过
|
||||
- [ ] 换行符正确
|
||||
- [ ] 无语法错误
|
||||
- [ ] 更新了 `memory-bank/progress.md`
|
||||
|
||||
---
|
||||
|
||||
**最后更新**：{{DATE}}
|
||||
@@ -0,0 +1,208 @@
|
||||
# 项目架构模板
|
||||
|
||||
本目录包含项目架构的模板文件，用于快速初始化新项目的 AI 代理工作环境。
|
||||
|
||||
## 目录结构
|
||||
|
||||
```text
|
||||
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
|
||||
│ └── implementation-plan.template.md
|
||||
├── prompts/ # 提示词库模板
|
||||
│ ├── README.md
|
||||
│ ├── system/
|
||||
│ │ └── agent-behavior.template.md
|
||||
│ └── coding/
|
||||
│ ├── clarify.template.md
|
||||
│ └── verify.template.md
|
||||
├── ci/ # CI 模板
|
||||
│ └── gitea/
|
||||
│ └── .gitea/workflows/
|
||||
├── cpp/ # C++ 配置模板
|
||||
│ ├── .clang-format
|
||||
│ ├── .clangd
|
||||
│ └── ...
|
||||
└── python/ # Python 配置模板
|
||||
├── .editorconfig
|
||||
├── pyproject.toml
|
||||
└── ...
|
||||
```
|
||||
|
||||
## 快速部署
|
||||
|
||||
使用 `sync_templates` 脚本一键部署：
|
||||
|
||||
**Linux/macOS**：
|
||||
|
||||
```bash
|
||||
# 基础部署
|
||||
sh scripts/sync_templates.sh /path/to/project
|
||||
|
||||
# 追加完整框架到已有 AGENTS.md
|
||||
sh scripts/sync_templates.sh --full /path/to/project
|
||||
```
|
||||
|
||||
**Windows PowerShell**：
|
||||
|
||||
```powershell
|
||||
# 基础部署
|
||||
.\scripts\sync_templates.ps1 -ProjectRoot C:\path\to\project
|
||||
|
||||
# 追加完整框架
|
||||
.\scripts\sync_templates.ps1 -ProjectRoot C:\path\to\project -Full
|
||||
```
|
||||
|
||||
**Windows CMD**：
|
||||
|
||||
```cmd
|
||||
scripts\sync_templates.bat C:\path\to\project
|
||||
scripts\sync_templates.bat --full C:\path\to\project
|
||||
```
|
||||
|
||||
### 部署行为
|
||||
|
||||
- **新项目**：创建完整的 AGENTS.md、AGENT_RULES.md、memory-bank/、docs/prompts/
|
||||
- **已有 AGENTS.md**：
|
||||
- 默认：追加路由链接（`<!-- playbook:templates:start/end -->`）
|
||||
- `--full`：追加完整框架（规则优先级 + 路由 + 新会话开始时）
|
||||
- **其他文件**：如果已存在则跳过（使用 `--force` 覆盖）
|
||||
- **自动创建**：TODO.md 和 CONFIRM.md（如果不存在）
|
||||
- **占位符替换**：自动替换 `{{DATE}}` 为当前日期
|
||||
|
||||
### 部署后的目录结构
|
||||
|
||||
```text
|
||||
project/
|
||||
├── AGENTS.md # 路由中心（主入口）
|
||||
├── AGENT_RULES.md # 执行流程
|
||||
├── TODO.md # 任务队列
|
||||
├── CONFIRM.md # 待确认事项
|
||||
├── memory-bank/ # 项目上下文
|
||||
│ ├── project-brief.md
|
||||
│ ├── tech-stack.md
|
||||
│ ├── architecture.md
|
||||
│ ├── progress.md
|
||||
│ ├── decisions.md
|
||||
│ └── implementation-plan.md
|
||||
└── docs/prompts/ # 提示词库
|
||||
├── README.md
|
||||
├── system/agent-behavior.md
|
||||
└── coding/
|
||||
├── clarify.md
|
||||
└── verify.md
|
||||
```
|
||||
|
||||
## 占位符说明
|
||||
|
||||
模板中使用 `{{PLACEHOLDER}}` 格式的占位符，需要替换为实际值：
|
||||
|
||||
| 占位符 | 说明 | 自动替换 |
|
||||
| ------------------------- | ------------ | -------- |
|
||||
| `{{DATE}}` | 日期 | ✅ 是 |
|
||||
| `{{PROJECT_NAME}}` | 项目名称 | ❌ 手动 |
|
||||
| `{{PROJECT_GOAL}}` | 项目目标 | ❌ 手动 |
|
||||
| `{{PROJECT_DESCRIPTION}}` | 项目描述 | ❌ 手动 |
|
||||
| `{{MAIN_LANGUAGE}}` | 主语言 | ❌ 手动 |
|
||||
| 其他 `{{...}}` | 项目特定内容 | ❌ 手动 |
|
||||
|
||||
## 模板说明
|
||||
|
||||
### memory-bank/
|
||||
|
||||
项目上下文文档，用于让 AI 快速理解项目：
|
||||
|
||||
| 文件 | 用途 |
|
||||
| --------------------------------- | -------------------- |
|
||||
| `project-brief.template.md` | 项目定位、边界、约束 |
|
||||
| `tech-stack.template.md` | 技术栈、工具链、环境 |
|
||||
| `architecture.template.md` | 架构设计、模块职责 |
|
||||
| `progress.template.md` | 开发进度追踪 |
|
||||
| `decisions.template.md` | 架构决策记录（ADR） |
|
||||
| `implementation-plan.template.md` | 当前实施计划 |
|
||||
|
||||
### prompts/
|
||||
|
||||
工作流程模板：
|
||||
|
||||
| 文件 | 用途 |
|
||||
| ----------------------------------- | ------------ |
|
||||
| `system/agent-behavior.template.md` | AI 行为规范 |
|
||||
| `coding/clarify.template.md` | 需求澄清模板 |
|
||||
| `coding/verify.template.md` | 验证检查清单 |
|
||||
|
||||
### AGENT_RULES.template.md
|
||||
|
||||
执行流程规范，定义 AI 的工作循环和约束。
|
||||
|
||||
### AGENTS.template.md
|
||||
|
||||
路由中心模板，作为项目的主入口。
|
||||
|
||||
**设计理念**：
|
||||
|
||||
- **最小化内容**：只包含导航链接，不包含详细规则
|
||||
- **结构化导航**：分为核心规则、项目上下文、工作流程三个板块
|
||||
|
||||
**playbook 标记**（用于自动更新）：
|
||||
|
||||
| 标记 | 用途 | 管理脚本 |
|
||||
| --------------------------------------- | ----------------------- | -------------- |
|
||||
| `<!-- playbook:agents:start/end -->` | 语言规则链接 | sync_standards |
|
||||
| `<!-- playbook:templates:start/end -->` | 路由链接（默认追加） | sync_templates |
|
||||
| `<!-- playbook:framework:start/end -->` | 完整框架（--full 追加） | sync_templates |
|
||||
|
||||
### ci/、cpp/、python/
|
||||
|
||||
语言和 CI 配置模板。通过 `vendor_playbook --apply-templates` 部署：
|
||||
|
||||
| 目录 | 内容 | 部署位置 |
|
||||
| ----------- | ----------------------------------------- | ---------- |
|
||||
| `ci/gitea/` | Gitea Actions 工作流 | `.gitea/` |
|
||||
| `cpp/` | .clang-format, .clangd, CMakeLists.txt 等 | 项目根目录 |
|
||||
| `python/` | pyproject.toml, .editorconfig 等 | 项目根目录 |
|
||||
|
||||
**使用方式**：
|
||||
|
||||
```bash
|
||||
# vendor_playbook 时一并部署
|
||||
sh scripts/vendor_playbook.sh /path/to/project tsl cpp --apply-templates
|
||||
```
|
||||
|
||||
## 与 playbook 其他部分的关系
|
||||
|
||||
```text
|
||||
playbook/
|
||||
├── rulesets/ # 语言级硬规则 → 部署到 .agents/
|
||||
├── codex/skills/ # 按需加载的技能
|
||||
├── docs/ # 权威静态文档
|
||||
├── templates/ # 本目录：项目架构模板 → 部署到 memory-bank/ 等
|
||||
└── scripts/
|
||||
├── sync_standards.* # 同步 .agents/ 和 .gitattributes
|
||||
└── sync_templates.* # 同步 memory-bank/、docs/prompts/、AGENT_RULES.md
|
||||
```
|
||||
|
||||
## 完整部署流程
|
||||
|
||||
```bash
|
||||
# 1. 部署项目架构模板
|
||||
sh scripts/sync_templates.sh /path/to/project
|
||||
|
||||
# 2. 部署语言规则
|
||||
sh scripts/sync_standards.sh tsl # 或其他语言
|
||||
|
||||
# 3. 编辑 memory-bank/*.md 填写项目信息
|
||||
|
||||
# 4. 替换剩余的 {{PLACEHOLDER}} 占位符
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**最后更新**：2026-01-21
|
||||
@@ -0,0 +1,110 @@
|
||||
# 架构设计
|
||||
|
||||
## 整体架构
|
||||
|
||||
```txt
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ {{LAYER_1}} │
|
||||
└─────────────────────┬───────────────────────────────────────┘
|
||||
│
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ {{LAYER_2}} │
|
||||
└─────────────────────┬───────────────────────────────────────┘
|
||||
│
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ {{LAYER_3}} │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## 核心模块
|
||||
|
||||
### 1. {{MODULE_1}}
|
||||
|
||||
**职责**：{{MODULE_1_DESC}}
|
||||
|
||||
**主要组件**：
|
||||
|
||||
- {{COMPONENT_1}}
|
||||
- {{COMPONENT_2}}
|
||||
|
||||
**核心方法**：
|
||||
|
||||
- {{METHOD_1}}
|
||||
- {{METHOD_2}}
|
||||
|
||||
---
|
||||
|
||||
### 2. {{MODULE_2}}
|
||||
|
||||
**职责**：{{MODULE_2_DESC}}
|
||||
|
||||
**主要组件**：
|
||||
|
||||
- {{COMPONENT_3}}
|
||||
- {{COMPONENT_4}}
|
||||
|
||||
---
|
||||
|
||||
### 3. {{MODULE_3}}
|
||||
|
||||
**职责**：{{MODULE_3_DESC}}
|
||||
|
||||
---
|
||||
|
||||
## 设计模式
|
||||
|
||||
### {{PATTERN_1}}
|
||||
|
||||
**应用**：{{PATTERN_1_USAGE}}
|
||||
|
||||
**目的**：{{PATTERN_1_PURPOSE}}
|
||||
|
||||
**优点**：
|
||||
|
||||
- {{PATTERN_1_ADVANTAGE_1}}
|
||||
- {{PATTERN_1_ADVANTAGE_2}}
|
||||
|
||||
### {{PATTERN_2}}
|
||||
|
||||
**应用**：{{PATTERN_2_USAGE}}
|
||||
|
||||
**目的**：{{PATTERN_2_PURPOSE}}
|
||||
|
||||
---
|
||||
|
||||
## 关键约束
|
||||
|
||||
### 1. {{CONSTRAINT_CATEGORY_1}}
|
||||
|
||||
- {{CONSTRAINT_1}}
|
||||
- {{CONSTRAINT_2}}
|
||||
|
||||
### 2. {{CONSTRAINT_CATEGORY_2}}
|
||||
|
||||
- {{CONSTRAINT_3}}
|
||||
- {{CONSTRAINT_4}}
|
||||
|
||||
---
|
||||
|
||||
## 扩展点
|
||||
|
||||
### 1. {{EXTENSION_1}}
|
||||
|
||||
**步骤**：
|
||||
|
||||
1. {{STEP_1}}
|
||||
2. {{STEP_2}}
|
||||
3. {{STEP_3}}
|
||||
|
||||
### 2. {{EXTENSION_2}}
|
||||
|
||||
**步骤**：
|
||||
|
||||
1. {{STEP_4}}
|
||||
2. {{STEP_5}}
|
||||
|
||||
---
|
||||
|
||||
**最后更新**：{{DATE}}
|
||||
@@ -0,0 +1,76 @@
|
||||
# 架构决策记录
|
||||
|
||||
本文档记录项目中的重要架构决策，使用 ADR (Architecture Decision Record) 格式。
|
||||
|
||||
---
|
||||
|
||||
## ADR-001: {{DECISION_1_TITLE}}
|
||||
|
||||
**日期**: {{DATE}}
|
||||
**状态**: 已采纳
|
||||
|
||||
### 决策
|
||||
|
||||
{{DECISION_1_CONTENT}}
|
||||
|
||||
### 理由
|
||||
|
||||
{{DECISION_1_REASON}}
|
||||
|
||||
### 影响
|
||||
|
||||
{{DECISION_1_IMPACT}}
|
||||
|
||||
### 实施细节
|
||||
|
||||
{{DECISION_1_IMPLEMENTATION}}
|
||||
|
||||
---
|
||||
|
||||
## ADR-002: {{DECISION_2_TITLE}}
|
||||
|
||||
**日期**: {{DATE}}
|
||||
**状态**: 已采纳
|
||||
|
||||
### 决策
|
||||
|
||||
{{DECISION_2_CONTENT}}
|
||||
|
||||
### 理由
|
||||
|
||||
{{DECISION_2_REASON}}
|
||||
|
||||
### 影响
|
||||
|
||||
{{DECISION_2_IMPACT}}
|
||||
|
||||
---
|
||||
|
||||
## ADR 模板
|
||||
|
||||
```markdown
|
||||
## ADR-XXX: 决策标题
|
||||
|
||||
**日期**: YYYY-MM-DD
|
||||
**状态**: 已采纳 / 已废弃 / 待讨论
|
||||
|
||||
### 决策
|
||||
|
||||
简要描述决策内容
|
||||
|
||||
### 理由
|
||||
|
||||
为什么做出这个决策
|
||||
|
||||
### 影响
|
||||
|
||||
对项目的影响
|
||||
|
||||
### 替代方案（可选）
|
||||
|
||||
考虑过但未采纳的方案
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**最后更新**：{{DATE}}
|
||||
@@ -0,0 +1,91 @@
|
||||
# 当前实施计划
|
||||
|
||||
## 计划状态
|
||||
|
||||
**计划名称**: {{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}}
|
||||
@@ -0,0 +1,60 @@
|
||||
# 开发进度追踪
|
||||
|
||||
## 当前阶段：{{CURRENT_PHASE}}
|
||||
|
||||
### 最近完成
|
||||
|
||||
#### {{DATE}}
|
||||
|
||||
- [x] {{COMPLETED_1}}
|
||||
- [x] {{COMPLETED_2}}
|
||||
|
||||
### 进行中
|
||||
|
||||
- [ ] {{IN_PROGRESS_1}}
|
||||
- [ ] {{IN_PROGRESS_2}}
|
||||
|
||||
### 待办
|
||||
|
||||
#### {{CATEGORY_1}}
|
||||
|
||||
- [ ] {{TODO_1}}
|
||||
- [ ] {{TODO_2}}
|
||||
|
||||
#### {{CATEGORY_2}}
|
||||
|
||||
- [ ] {{TODO_3}}
|
||||
- [ ] {{TODO_4}}
|
||||
|
||||
### 已知问题
|
||||
|
||||
#### {{ISSUE_CATEGORY_1}}
|
||||
|
||||
- {{ISSUE_1}}
|
||||
- **临时方案**：{{WORKAROUND_1}}
|
||||
- **长期方案**：{{SOLUTION_1}}
|
||||
|
||||
### 里程碑
|
||||
|
||||
#### M1: {{MILESTONE_1}}（目标：{{TARGET_DATE_1}}）
|
||||
|
||||
- [ ] {{MILESTONE_1_TASK_1}}
|
||||
- [ ] {{MILESTONE_1_TASK_2}}
|
||||
|
||||
#### M2: {{MILESTONE_2}}（目标：{{TARGET_DATE_2}}）
|
||||
|
||||
- [ ] {{MILESTONE_2_TASK_1}}
|
||||
- [ ] {{MILESTONE_2_TASK_2}}
|
||||
|
||||
---
|
||||
|
||||
## 更新日志
|
||||
|
||||
### {{DATE}}
|
||||
|
||||
- {{LOG_1}}
|
||||
- {{LOG_2}}
|
||||
|
||||
---
|
||||
|
||||
**最后更新**：{{DATE}}
|
||||
@@ -0,0 +1,66 @@
|
||||
# {{PROJECT_NAME}} 项目简介
|
||||
|
||||
## 项目定位
|
||||
|
||||
**核心目标**：{{PROJECT_GOAL}}
|
||||
|
||||
**一句话描述**：{{PROJECT_DESCRIPTION}}
|
||||
|
||||
## 为什么做这个项目？
|
||||
|
||||
### 问题
|
||||
|
||||
- {{PROBLEM_1}}
|
||||
- {{PROBLEM_2}}
|
||||
- {{PROBLEM_3}}
|
||||
|
||||
### 解决方案
|
||||
|
||||
- {{SOLUTION_1}}
|
||||
- {{SOLUTION_2}}
|
||||
- {{SOLUTION_3}}
|
||||
|
||||
## 项目边界
|
||||
|
||||
### 做什么
|
||||
|
||||
- {{DO_1}}
|
||||
- {{DO_2}}
|
||||
- {{DO_3}}
|
||||
|
||||
### 不做什么
|
||||
|
||||
- {{DONT_1}}
|
||||
- {{DONT_2}}
|
||||
- {{DONT_3}}
|
||||
|
||||
### 约束条件
|
||||
|
||||
- {{CONSTRAINT_1}}
|
||||
- {{CONSTRAINT_2}}
|
||||
- {{CONSTRAINT_3}}
|
||||
|
||||
## 核心概念
|
||||
|
||||
<!-- 根据项目需要填写核心概念 -->
|
||||
|
||||
## 技术栈
|
||||
|
||||
- **主语言**：{{MAIN_LANGUAGE}}
|
||||
- **外部依赖**：{{DEPENDENCIES}}
|
||||
- **测试环境**：{{TEST_ENV}}
|
||||
|
||||
## 参考资料
|
||||
|
||||
- {{REFERENCE_1}}
|
||||
- {{REFERENCE_2}}
|
||||
|
||||
## 当前状态
|
||||
|
||||
- {{STATUS_1}}
|
||||
- {{STATUS_2}}
|
||||
- {{STATUS_3}}
|
||||
|
||||
---
|
||||
|
||||
**最后更新**：{{DATE}}
|
||||
@@ -0,0 +1,118 @@
|
||||
# 技术栈与工具链
|
||||
|
||||
## 核心技术
|
||||
|
||||
### 主语言：{{MAIN_LANGUAGE}}
|
||||
|
||||
**文件类型**：
|
||||
|
||||
- {{FILE_TYPE_1}}
|
||||
- {{FILE_TYPE_2}}
|
||||
|
||||
**特点**：
|
||||
|
||||
- {{FEATURE_1}}
|
||||
- {{FEATURE_2}}
|
||||
- {{FEATURE_3}}
|
||||
|
||||
**运行方式**：
|
||||
|
||||
- {{RUN_METHOD_1}}
|
||||
- {{RUN_METHOD_2}}
|
||||
|
||||
## 项目结构
|
||||
|
||||
```text
|
||||
{{PROJECT_NAME}}/
|
||||
├── {{DIR_1}}/ # {{DIR_1_DESC}}
|
||||
├── {{DIR_2}}/ # {{DIR_2_DESC}}
|
||||
├── {{DIR_3}}/ # {{DIR_3_DESC}}
|
||||
└── memory-bank/ # 项目上下文
|
||||
```
|
||||
|
||||
## 开发环境
|
||||
|
||||
### {{ENV_1}}
|
||||
|
||||
**必需工具**：
|
||||
|
||||
- {{TOOL_1}}
|
||||
- {{TOOL_2}}
|
||||
|
||||
**运行测试**：
|
||||
|
||||
```bash
|
||||
{{TEST_CMD_1}}
|
||||
```
|
||||
|
||||
### {{ENV_2}}（如有）
|
||||
|
||||
**必需工具**：
|
||||
|
||||
- {{TOOL_3}}
|
||||
- {{TOOL_4}}
|
||||
|
||||
## 版本控制
|
||||
|
||||
### Git 配置
|
||||
|
||||
**换行规则**（`.gitattributes`）：
|
||||
|
||||
- 遵循 `.gitattributes` 文件定义
|
||||
|
||||
**忽略规则**（`.gitignore`）：
|
||||
|
||||
- 以 `.gitignore` 实际内容为准
|
||||
|
||||
### 分支策略
|
||||
|
||||
- `master`/`main`：主分支（稳定版本）
|
||||
- 功能分支：按需创建
|
||||
|
||||
## 测试策略
|
||||
|
||||
### 测试类型
|
||||
|
||||
- {{TEST_TYPE_1}}
|
||||
- {{TEST_TYPE_2}}
|
||||
|
||||
### 验证标准
|
||||
|
||||
**测试通过条件**：
|
||||
|
||||
1. {{PASS_CONDITION_1}}
|
||||
2. {{PASS_CONDITION_2}}
|
||||
3. {{PASS_CONDITION_3}}
|
||||
|
||||
**常见失败原因**：
|
||||
|
||||
- {{FAIL_REASON_1}}
|
||||
- {{FAIL_REASON_2}}
|
||||
|
||||
## 依赖管理
|
||||
|
||||
### 外部依赖
|
||||
|
||||
- {{EXTERNAL_DEP_1}}
|
||||
- {{EXTERNAL_DEP_2}}
|
||||
|
||||
### 内部依赖
|
||||
|
||||
- {{INTERNAL_DEP_1}}
|
||||
- {{INTERNAL_DEP_2}}
|
||||
|
||||
## 性能考虑
|
||||
|
||||
### 当前瓶颈
|
||||
|
||||
- {{BOTTLENECK_1}}
|
||||
- {{BOTTLENECK_2}}
|
||||
|
||||
### 优化方向
|
||||
|
||||
- {{OPTIMIZATION_1}}
|
||||
- {{OPTIMIZATION_2}}
|
||||
|
||||
---
|
||||
|
||||
**最后更新**：{{DATE}}
|
||||
@@ -0,0 +1,42 @@
|
||||
# 提示词库
|
||||
|
||||
本目录包含 AI 代理的工作流程模板和参考文档。
|
||||
|
||||
## 目录结构
|
||||
|
||||
```text
|
||||
prompts/
|
||||
├── README.md # 本文件
|
||||
├── system/ # 系统级规范
|
||||
│ └── agent-behavior.md
|
||||
├── coding/ # 编码流程
|
||||
│ ├── clarify.md # 需求澄清模板
|
||||
│ └── verify.md # 验证检查清单
|
||||
└── user/ # 用户快捷命令
|
||||
└── quick-test.md # 快速测试命令
|
||||
```
|
||||
|
||||
## 使用方式
|
||||
|
||||
### AI 代理
|
||||
|
||||
- 新会话时读取 `system/agent-behavior.md`
|
||||
- 需要澄清需求时参考 `coding/clarify.md`
|
||||
- 完成任务前检查 `coding/verify.md`
|
||||
|
||||
### 用户
|
||||
|
||||
- 使用 `user/quick-test.md` 中的命令快速执行测试
|
||||
|
||||
## 文档说明
|
||||
|
||||
| 文件 | 用途 |
|
||||
| -------------------------- | ------------------------------- |
|
||||
| `system/agent-behavior.md` | AI 行为规范、工作模式、禁止行为 |
|
||||
| `coding/clarify.md` | 需求澄清步骤和问题模板 |
|
||||
| `coding/verify.md` | 代码、测试、文档验证清单 |
|
||||
| `user/quick-test.md` | 常用测试命令参考 |
|
||||
|
||||
---
|
||||
|
||||
**最后更新**：{{DATE}}
|
||||
@@ -0,0 +1,129 @@
|
||||
# 需求澄清模板
|
||||
|
||||
## 何时使用
|
||||
|
||||
- 需求描述不明确
|
||||
- 存在多种理解方式
|
||||
- 缺少关键信息
|
||||
|
||||
---
|
||||
|
||||
## 澄清步骤
|
||||
|
||||
### 1. 理解当前需求
|
||||
|
||||
**复述需求**：
|
||||
|
||||
```text
|
||||
我理解你的需求是：[用自己的话复述]
|
||||
```
|
||||
|
||||
**识别歧义点**：
|
||||
|
||||
- 歧义 1：[描述不明确的地方]
|
||||
- 歧义 2：[可能有多种理解的地方]
|
||||
|
||||
---
|
||||
|
||||
### 2. 提出澄清问题
|
||||
|
||||
**问题模板**：
|
||||
|
||||
> 只问阻塞问题，最多 1–2 个；优先给出选项让用户选择。
|
||||
|
||||
#### 功能范围
|
||||
|
||||
- 这个功能是否包括 [场景 A]？
|
||||
- 是否需要支持 [边界情况 B]？
|
||||
- 优先级如何？必须有 vs 可选
|
||||
|
||||
#### 行为细节
|
||||
|
||||
- 当 [条件 X] 时，应该 [行为 Y] 还是 [行为 Z]？
|
||||
- 如果 [异常情况]，如何处理？
|
||||
- 是否需要与 [现有功能] 保持一致？
|
||||
|
||||
#### 技术约束
|
||||
|
||||
- 是否有性能要求？
|
||||
- 是否有兼容性要求？
|
||||
- 是否有安全要求？
|
||||
|
||||
---
|
||||
|
||||
### 3. 提供选项
|
||||
|
||||
**选项格式**：
|
||||
|
||||
**选项 A**：[方案描述]
|
||||
|
||||
- 优点：[列出优点]
|
||||
- 缺点：[列出缺点]
|
||||
- 适用场景：[什么情况下选这个]
|
||||
|
||||
**选项 B**：[方案描述]
|
||||
|
||||
- 优点：[列出优点]
|
||||
- 缺点：[列出缺点]
|
||||
- 适用场景：[什么情况下选这个]
|
||||
|
||||
**推荐**：[推荐哪个选项，为什么]
|
||||
|
||||
---
|
||||
|
||||
### 4. 确认理解
|
||||
|
||||
**确认清单**：
|
||||
|
||||
- [ ] 功能范围明确
|
||||
- [ ] 行为细节清晰
|
||||
- [ ] 技术约束已知
|
||||
- [ ] 优先级确定
|
||||
- [ ] 验收标准明确
|
||||
|
||||
---
|
||||
|
||||
## 示例
|
||||
|
||||
### 需求
|
||||
|
||||
```text
|
||||
实现 XXX 功能
|
||||
```
|
||||
|
||||
### 澄清过程
|
||||
|
||||
**复述需求**：
|
||||
|
||||
```text
|
||||
我理解你的需求是：为 YYY 添加 XXX 功能，
|
||||
用于 ZZZ。
|
||||
```
|
||||
|
||||
**识别歧义点**：
|
||||
|
||||
- 歧义 1：XXX 是只读还是可写？
|
||||
- 歧义 2：是否需要支持所有场景？
|
||||
|
||||
**澄清问题**：
|
||||
|
||||
- 是否需要支持 [场景 A]？
|
||||
- 当 [条件 X] 时，应该如何处理？
|
||||
|
||||
**提供选项**：
|
||||
|
||||
**选项 A**：完整实现
|
||||
|
||||
- 优点：功能完整
|
||||
- 缺点：开发周期长
|
||||
|
||||
**选项 B**：核心功能
|
||||
|
||||
- 优点：快速交付
|
||||
- 缺点：功能有限
|
||||
|
||||
**推荐**：选项 A，因为 [原因]。
|
||||
|
||||
---
|
||||
|
||||
**最后更新**：{{DATE}}
|
||||
@@ -0,0 +1,94 @@
|
||||
# 验证检查清单
|
||||
|
||||
## 代码修改验证
|
||||
|
||||
### 语法检查
|
||||
|
||||
- [ ] 代码可正常运行（无语法错误）
|
||||
- [ ] 无未定义的变量或函数
|
||||
- [ ] 依赖引用正确
|
||||
|
||||
### 风格检查
|
||||
|
||||
- [ ] 命名符合规范
|
||||
- [ ] 缩进正确
|
||||
- [ ] 换行符正确（遵循 .gitattributes）
|
||||
- [ ] 无冗余注释
|
||||
|
||||
---
|
||||
|
||||
## 测试验证
|
||||
|
||||
### 单元测试
|
||||
|
||||
- [ ] 相关测试脚本存在
|
||||
- [ ] 测试可正常运行
|
||||
- [ ] 测试通过（无失败）
|
||||
|
||||
### 回归测试
|
||||
|
||||
- [ ] 现有测试仍然通过
|
||||
- [ ] 未破坏其他功能
|
||||
|
||||
---
|
||||
|
||||
## 文档验证
|
||||
|
||||
### 代码文档
|
||||
|
||||
- [ ] 复杂逻辑有注释说明
|
||||
- [ ] 公开 API 有使用示例（如需）
|
||||
|
||||
### 项目文档
|
||||
|
||||
- [ ] `memory-bank/progress.md` 已更新
|
||||
- [ ] 重要决策记录到 `memory-bank/decisions.md`
|
||||
- [ ] `CONFIRM.md` 中需讨论事项已记录
|
||||
|
||||
---
|
||||
|
||||
## Git 验证
|
||||
|
||||
### 提交前检查
|
||||
|
||||
- [ ] 只包含相关修改（无无关文件）
|
||||
- [ ] 提交信息清晰
|
||||
- [ ] 无临时文件或调试代码
|
||||
|
||||
### 分支检查
|
||||
|
||||
- [ ] 在正确的分支上工作
|
||||
|
||||
---
|
||||
|
||||
## 性能验证（如果涉及）
|
||||
|
||||
### 性能测试
|
||||
|
||||
- [ ] 处理时间可接受
|
||||
- [ ] 内存使用正常
|
||||
- [ ] 无明显性能退化
|
||||
|
||||
---
|
||||
|
||||
## 安全验证（如果涉及）
|
||||
|
||||
### 安全检查
|
||||
|
||||
- [ ] 无注入风险
|
||||
- [ ] 敏感信息已脱敏
|
||||
|
||||
---
|
||||
|
||||
## 快速检查清单（最小集）
|
||||
|
||||
**每次修改必须检查**：
|
||||
|
||||
- [ ] 代码可运行（无语法错误）
|
||||
- [ ] 相关测试通过
|
||||
- [ ] 换行符正确
|
||||
- [ ] `memory-bank/progress.md` 已更新
|
||||
|
||||
---
|
||||
|
||||
**最后更新**：{{DATE}}
|
||||
@@ -0,0 +1,196 @@
|
||||
# AI 代理行为规范
|
||||
|
||||
## 工作模式
|
||||
|
||||
### 模式 1: 探索模式（Explore）
|
||||
|
||||
**目的**：理解代码库、分析问题、收集信息
|
||||
|
||||
**行为规范**：
|
||||
|
||||
- 使用搜索工具探索代码
|
||||
- 输出分析报告和发现
|
||||
- 提出问题和建议
|
||||
- 不修改任何代码
|
||||
- 不运行测试（除非明确要求）
|
||||
|
||||
**适用场景**：
|
||||
|
||||
- 理解某个模块的实现
|
||||
- 分析 bug 的根本原因
|
||||
- 评估功能实现的可行性
|
||||
|
||||
---
|
||||
|
||||
### 模式 2: 开发模式（Develop）
|
||||
|
||||
**目的**：实现功能、修复 bug、重构代码
|
||||
|
||||
**行为规范**：
|
||||
|
||||
- 先读取相关文件，理解现有逻辑
|
||||
- 进行精确修改
|
||||
- 修改后运行对应测试验证
|
||||
- 更新 `memory-bank/progress.md`
|
||||
- 不读文件就提议修改
|
||||
- 不跳过测试直接提交
|
||||
|
||||
**适用场景**：
|
||||
|
||||
- 实现新功能
|
||||
- 修复已知 bug
|
||||
- 优化性能
|
||||
|
||||
---
|
||||
|
||||
### 模式 3: 调试模式（Debug）
|
||||
|
||||
**目的**：诊断问题、对比差异、验证行为
|
||||
|
||||
**行为规范**：
|
||||
|
||||
- 收集相关日志和输出
|
||||
- 分析差异原因
|
||||
- 记录到 `CONFIRM.md` 或直接修复
|
||||
- 重新验证
|
||||
|
||||
**适用场景**：
|
||||
|
||||
- 测试失败
|
||||
- 输出不符合预期
|
||||
- 性能问题诊断
|
||||
|
||||
---
|
||||
|
||||
## 代码风格要求
|
||||
|
||||
### 通用规范
|
||||
|
||||
**命名规范**：
|
||||
|
||||
- 遵循项目现有的命名风格
|
||||
- 保持一致性
|
||||
|
||||
**缩进**：
|
||||
|
||||
- 遵循项目现有的缩进风格
|
||||
|
||||
**换行**：
|
||||
|
||||
- 遵循 `.gitattributes` 规则
|
||||
|
||||
**注释**：
|
||||
|
||||
- 只在逻辑不自明时添加注释
|
||||
- 不添加冗余注释
|
||||
|
||||
---
|
||||
|
||||
## 禁止行为清单
|
||||
|
||||
### 代码修改
|
||||
|
||||
- **不读文件就提议修改**
|
||||
|
||||
- 必须先读取文件
|
||||
- 理解现有逻辑后再提出修改建议
|
||||
|
||||
- **破坏现有架构**
|
||||
|
||||
- 不随意移动目录结构
|
||||
- 不随意重构核心模块
|
||||
|
||||
- **随意改动换行符**
|
||||
- 遵循 `.gitattributes` 规则
|
||||
- 不混用 LF 和 CRLF
|
||||
|
||||
### 测试流程
|
||||
|
||||
- **跳过测试直接提交**
|
||||
- 修改后必须运行相关测试
|
||||
- 测试失败必须分析原因
|
||||
|
||||
### Git 操作
|
||||
|
||||
- **使用 `git commit --amend`**
|
||||
|
||||
- 除非用户明确要求
|
||||
- 总是创建新提交
|
||||
|
||||
- **使用 `git push --force`**
|
||||
|
||||
- 特别是推送到 main/master 分支
|
||||
- 如果用户要求，必须警告风险
|
||||
|
||||
- **跳过 hooks**
|
||||
- 不使用 `--no-verify`
|
||||
|
||||
### 过度工程
|
||||
|
||||
- **添加未要求的功能**
|
||||
|
||||
- 只做用户要求的修改
|
||||
- 不主动重构周边代码
|
||||
|
||||
- **添加不必要的注释**
|
||||
|
||||
- 不给自明的代码添加注释
|
||||
|
||||
- **过度抽象**
|
||||
- 不为一次性操作创建工具函数
|
||||
- 不为假设的未来需求设计
|
||||
|
||||
---
|
||||
|
||||
## 决策原则
|
||||
|
||||
### 何时记录到 CONFIRM.md
|
||||
|
||||
**必须记录**：
|
||||
|
||||
- 需求有歧义，存在多种理解
|
||||
- 有多个技术方案，需要权衡
|
||||
- 可能破坏兼容性
|
||||
- 涉及架构变更
|
||||
|
||||
**可以不记录**：
|
||||
|
||||
- 明显的 bug 修复
|
||||
- 符合现有模式的小改动
|
||||
- 测试用例补充
|
||||
|
||||
### 何时记录到 decisions.md
|
||||
|
||||
**必须记录**（ADR 格式）：
|
||||
|
||||
- 影响多个模块的架构决策
|
||||
- 技术栈选择
|
||||
- 设计模式选择
|
||||
- 重要的约束条件
|
||||
|
||||
---
|
||||
|
||||
## 沟通原则
|
||||
|
||||
### 输出风格
|
||||
|
||||
- 简洁明确，避免冗长
|
||||
- 使用纯文本结构化输出，必要时用 Markdown 代码块
|
||||
- 代码块标注语言
|
||||
- 不使用 emoji（除非用户明确要求）
|
||||
- 不使用过度的赞美或验证
|
||||
|
||||
### 技术准确性
|
||||
|
||||
- 优先技术准确性，而非迎合用户
|
||||
- 发现用户理解有误时，礼貌纠正
|
||||
- 不确定时，先调查再回答
|
||||
|
||||
### 时间估算
|
||||
|
||||
- 不给出时间估算
|
||||
- 专注于任务本身，让用户自己判断时间
|
||||
|
||||
---
|
||||
|
||||
**最后更新**：{{DATE}}
|
||||
Reference in New Issue
Block a user