📝 docs(markdown): format tracked markdown and drop stale templates

2026-05-18 16:06:21 +08:00
parent 2325409f53
commit c1702a667a
16 changed files with 184 additions and 421 deletions
@@ -1,44 +0,0 @@
-# 架构设计
-
-<!--
-填写指南：
- 【必填】：项目启动前必须填写
- 【可选】：按需填写，可随项目发展补充
- 小项目可只填核心模块，架构图可后补
-->
-
-## 整体架构
-
-<!-- 【可选】项目成熟后补充 -->
-
-```txt
-{{ARCHITECTURE_DIAGRAM}}
-```
-
-## 核心模块
-
-<!-- 【必填】至少列出主要模块 -->
-
-### {{MODULE_1}}
-
-**职责**：{{MODULE_1_DESC}}
-
-## 关键约束
-
-<!-- 【可选】 -->
-
- {{CONSTRAINT_1}}
-
-## 扩展点
-
-<!-- 【可选】大项目建议填写 -->
-
-### {{EXTENSION_1}}
-
-**步骤**：
-
-1. {{STEP_1}}
-
---
-
-**最后更新**：{{DATE}}
@@ -1,62 +0,0 @@
-# 技术栈与工具链
-
-<!--
-填写指南：
- 【必填】：项目启动前必须填写
- 【可选】：按需填写，可随项目发展补充
- 未填写的占位符保持原样或删除整行
-->
-
-## 核心技术
-
-<!-- 【必填】 -->
-
-**文件类型**：{{FILE_TYPES}}
-
-## 项目结构
-
-<!-- 【必填】 -->
-
-```text
-{{PROJECT_NAME}}/
-├── {{DIR_1}}/           # {{DIR_1_DESC}}
-└── memory-bank/         # 项目上下文
-```
-
-## 开发环境
-
-<!-- 【必填】至少填写运行测试命令 -->
-
-**必需工具**：
-
- {{TOOL_1}}
-
-**运行测试**：
-
-```bash
-{{TEST_CMD}}
-```
-
-## 依赖管理
-
-<!-- 【可选】 -->
-
-**外部依赖**：
-
- {{EXTERNAL_DEP_1}}
-
-## 测试策略
-
-<!-- 【可选】大项目建议填写 -->
-
-**测试类型**：
-
- {{TEST_TYPE_1}}
-
-**验证标准**：
-
- {{PASS_CONDITION_1}}
-
---
-
-**最后更新**：{{DATE}}
@@ -1,6 +1,6 @@
-# 提示词库
+# 提示词入口

-本目录包含 AI 代理的工作流程参考模板。
+本目录包含 AI 代理的工作流入口模板，用于把任务路由到合适的执行路径。

 ## 目录结构

@@ -8,44 +8,62 @@
 prompts/
 ├── README.md              # 本文件
 ├── system/
-│   └── agent-behavior.md  # 工作模式参考
+│   └── agent-behavior.md  # 工作流入口
 ├── coding/
 │   ├── clarify.md         # 需求澄清模板
-│   ├── review.md          # 复盘总结模板
+│   ├── verify-change.md   # 变更验证模板
+│   ├── close-task.md      # 本轮收尾模板
+│   ├── update-memory.md   # 回写记忆模板
 │   └── code-review.md     # MR/PR 代码评审流程
-└── meta/
-    └── prompt-generator.md # 元提示词生成器
 ```

 ## 使用方式

-| 模板                    | 触发场景                       |
-| ----------------------- | ------------------------------ |
-| **agent-behavior.md**   | 切换工作模式（探索/开发/调试） |
-| **clarify.md**          | 需求不明确时澄清               |
-| **review.md**           | Plan 完成后复盘总结            |
-| **code-review.md**      | 执行 MR/PR 代码评审            |
-| **prompt-generator.md** | 创建新的专用提示词             |
+| 模板                  | 触发场景             |
+| --------------------- | -------------------- |
+| **agent-behavior.md** | 选择工作流入口       |
+| **clarify.md**        | 需求不明确时澄清     |
+| **verify-change.md**  | 声称完成前做验证     |
+| **close-task.md**     | 本轮工作收尾         |
+| **update-memory.md**  | 上下文变化后回写记忆 |
+| **code-review.md**    | 执行 MR/PR 代码评审  |

 ## 工作流程

-```
+```text
 需求不清 → clarify.md
    ↓
-头脑风暴 → $brainstorming skill
+入口约束 → using-superpowers
    ↓
-生成计划 → $writing-plans skill → docs/plans/*.md
+头脑风暴 → $brainstorming skill → docs/superpowers/specs/*-design.md
    ↓
-执行计划 → AGENT_RULES 主循环（`main_loop.py claim/finish` 留痕）
+spec 完成后 → `playbook.py -record-spec <path> -progress memory-bank/progress.md`
+    ↓
+生成计划 → $writing-plans skill → docs/superpowers/plans/*.md
+    ↓
+plan 完成后 → `playbook.py -record-plan <path> -progress memory-bank/progress.md`
+    ↓
+领取计划 → `main_loop.py claim`
+    ↓
+执行计划 → `$executing-plans`
+    ↓
+代码类任务 → `karpathy-guidelines` + `.agents/` + `AGENT_RULES.md`
+    ↓
+写回状态 → `main_loop.py finish`
+    ↓
+更新摘要 → update-memory.md
+    ↓
+验证改动 → verify-change.md
+    ↓
+本轮收尾 → close-task.md
    ↓
 代码评审（有 MR/PR 时）→ code-review.md
-    ↓
-完成复盘 → review.md
-    ↓
-沉淀提示词 → prompt-generator.md（可选）
 ```

-> **核心规则在 `AGENT_RULES.md`**，第三方 skills 只负责规划；执行与留痕必须走 `main_loop.py claim/finish`。
+> `prompts/` 是入口层；核心规则在 `AGENT_RULES.md`，
+> 长期记忆在 `memory-bank/`，状态留痕必须走
+> `playbook.py -record-spec/-record-plan` 与
+> `main_loop.py claim/finish`。

 ---

@@ -69,12 +69,12 @@ gh pr diff <PR_NUMBER>

 ## AI 与人工的分工

-| 维度 | 负责方 | 说明 |
-| ---- | ------ | ---- |
-| Bug、逻辑漏洞、安全问题 | **AI + 人工** | AI 负责初筛与证据收集，结论需人工复核 |
-| 代码清晰度、KISS、单一职责 | **AI + 人工** | AI 提供候选问题，人工决定是否采纳 |
-| 架构合理性、业务对齐 | **人工** | AI 反馈少且准确率低，需人工把关 |
-| 兼容性、历史债务、战略取舍 | **人工** | 依赖背景知识，AI 难以判断 |
+| 维度                       | 负责方        | 说明                                  |
+| -------------------------- | ------------- | ------------------------------------- |
+| Bug、逻辑漏洞、安全问题    | **AI + 人工** | AI 负责初筛与证据收集，结论需人工复核 |
+| 代码清晰度、KISS、单一职责 | **AI + 人工** | AI 提供候选问题，人工决定是否采纳     |
+| 架构合理性、业务对齐       | **人工**      | AI 反馈少且准确率低，需人工把关       |
+| 兼容性、历史债务、战略取舍 | **人工**      | 依赖背景知识，AI 难以判断             |

 > 规则：AI 结论必须附文件路径、行号或可复现依据；缺少证据时按待确认假设处理。
 >
@@ -1,66 +0,0 @@
-# 复盘模板
-
-<!--
-用途：Plan 或阶段完成后的回顾总结
-触发：主循环汇总报告时、阶段性工作完成时
-->
-
-## 何时使用
-
- 一批 Plan 执行完毕后
- 阶段性工作告一段落
- 遇到重大阻塞需要总结
-
---
-
-## 复盘格式
-
-```markdown
-# 复盘: [日期/阶段名称]
-
-## 完成情况
-
-### 已完成
- [x] Plan 1: 简述
- [x] Plan 2: 简述
-
-### 阻塞
- [ ] Plan 3: 阻塞原因
-
-### 跳过
- [ ] Plan 4: 跳过原因
-
-## 关键发现
-
-### 做得好的
- 发现1
- 发现2
-
-### 待改进
- 问题1 → 建议改进方式
- 问题2 → 建议改进方式
-
-## 决策记录
-
-| 决策 | 理由 | 影响 |
-|------|------|------|
-| 决策1 | 为什么 | 影响范围 |
-
-## 下一步
-
- [ ] 待处理事项1
- [ ] 待处理事项2
-```
-
---
-
-## 复盘原则
-
- **客观记录**：如实记录完成/阻塞/跳过
- **提取经验**：总结做得好的和待改进的
- **决策留痕**：重要决策记录到 decisions.md
- **明确下一步**：列出后续待处理事项
-
---
-
-**最后更新**：{{DATE}}