会话模板应用器

⚠️ 强制：首先阅读项目文档

在应用会话模板之前，您必须阅读并理解以下项目文档：

核心项目文档

README.md - 项目概览，特性和入门指南
AI_DOCS/project-context.md - 技术栈，架构，开发工作流
AI_DOCS/code-conventions.md - 代码风格，格式化，最佳实践
AI_DOCS/tdd-workflow.md - TDD流程，测试标准，覆盖率要求

会话上下文（如果可用）

.ai-context/ACTIVE_TASKS.md - 当前任务和优先级
.ai-context/CONVENTIONS.md - 项目特定约定
.ai-context/RECENT_DECISIONS.md - 最近的架构决策
.ai-context/LAST_SESSION_SUMMARY.md - 上次会话总结

额外的AI文档

AI_DOCS/ai-tools.md - 会话管理工作流（对于这项技能至关重要）
AI_DOCS/ai-skills.md - 其他专业技能/代理可用

为什么这很重要

工作流集成：了解ai-update-plan如何融入会话管理
模板选择：根据项目模式选择合适的模板
定制：适应模板以匹配项目特定要求
任务上下文：在规划时考虑活跃任务和最近的决策

阅读这些文件后，请继续进行下面的模板应用任务。

概览

自动将任务特定的计划模板应用到AI会话中，使用任务特定的细节定制通用步骤。

何时使用

开始一个新的AI会话与ai-start-task
需要常见任务类型的结构化计划
想要确保所有重要步骤都包含在内
标准化团队的工作流
需要全面规划的复杂任务

可用模板

1. 功能开发（`feature`）

用于添加新功能

2. 错误修复（`bugfix`）

用于修复现有问题

3. 重构（`refactor`）

用于代码改进而不改变行为

4. 文档编写（`documentation`）

用于文档更新和改进

5. 安全修复（`security`）

用于安全漏洞和加固

使用示例

在会话开始时应用模板

# 使用功能模板开始会话
apply feature development template for "Add OAuth2 authentication"

输出： 创建会话，包括：

研究与设计阶段
TDD测试编写阶段
实施阶段
安全审查阶段
文档编写阶段

将模板应用于现有会话

# 中途会话，意识到你需要结构化计划
apply refactoring template for current session

自定义模板选择

# 让技能分析任务并选择模板
suggest template for "Fix memory leak in data processor"
# → 技能建议："bugfix"模板

模板结构

功能模板

文件： templates/feature.md

### 第1阶段：研究与设计
- [ ] 审查代码库中的相关代码
- [ ] 确定集成点
- [ ] 设计数据模型和接口
- [ ] 文档化API契约
- [ ] 考虑边缘情况和错误场景

### 第2阶段：编写测试（TDD）
- [ ] 为快乐路径场景编写测试
- [ ] 为边缘情况编写测试
- [ ] 为错误处理编写测试
- [ ] 编写集成测试
- [ ] 确保测试最初失败（红色阶段）

### 第3阶段：实施
- [ ] 实施核心功能
- [ ] 添加错误处理
- [ ] 添加输入验证
- [ ] 添加日志记录
- [ ] 运行测试 - 应该通过（绿色阶段）

### 第4阶段：重构
- [ ] 删除重复（DRY）
- [ ] 简化复杂逻辑
- [ ] 改进命名
- [ ] 添加缺失的类型提示
- [ ] 保持测试通过

### 第5阶段：质量检查
- [ ] 运行make检查（格式化，lint，测试，安全）
- [ ] 修复所有质量问题
- [ ] 验证覆盖率≥80%
- [ ] 与tdd-reviewer代理审查
- [ ] 应用quality-fixer自动修复可修复的问题

### 第6阶段：文档编写
- [ ] 如果用户面向变化更新README
- [ ] 添加/更新文档字符串
- [ ] 更新API文档
- [ ] 添加使用示例
- [ ] 文档配置更改

### 第7阶段：最终审查
- [ ] 使用git diff审查所有更改
- [ ] 在开发中手动测试
- [ ] 验证所有边缘情况工作
- [ ] 检查性能影响
- [ ] 准备PR/提交

Bugfix模板

文件： templates/bugfix.md

### 第1阶段：重现
- [ ] 可靠地重现bug
- [ ] 文档化重现步骤
- [ ] 确定受影响的组件
- [ ] 检查是否回归（之前工作）
- [ ] 审查相关的问题

### 第2阶段：根本原因分析
- [ ] 添加调试日志
- [ ] 追踪执行流程
- [ ] 确定确切的失败点
- [ ] 理解为什么失败
- [ ] 文档化根本原因

### 第3阶段：编写重现测试（TDD）
- [ ] 编写测试重现bug
- [ ] 验证测试失败（确认bug存在）
- [ ] 测试应该针对bug具体
- [ ] 包括与bug相关的边缘情况
- [ ] 文档化预期与实际行为

### 第4阶段：修复实施
- [ ] 实施针对根本原因的最小修复
- [ ] 避免过度工程修复
- [ ] 如果需要，添加防御性检查
- [ ] 添加日志记录以便于未来的调试
- [ ] 验证测试现在通过

### 第5阶段：回归预防
- [ ] 为相关场景添加测试
- [ ] 检查bug是否在其他地方存在
- [ ] 添加验证以防止再次发生
- [ ] 如果适用，更新错误消息
- [ ] 文档化为什么会出现bug

### 第6阶段：质量与测试
- [ ] 运行完整测试套件（无回归）
- [ ] 运行make检查
- [ ] 验证覆盖率维持/提高
- [ ] 使用原始报告步骤手动测试
- [ ] 检查性能没有降低

### 第7阶段：文档编写
- [ ] 更新变更日志
- [ ] 在提交消息中记录修复
- [ ] 添加代码注释解释修复
- [ ] 如果行为改变，更新文档
- [ ] 如果适用，引用问题编号

重构模板

文件： templates/refactor.md

### 第1阶段：建立安全网
- [ ] 确保被重构的代码存在测试
- [ ] 运行测试 - 所有必须通过（基线）
- [ ] 运行make检查 - 必须通过
- [ ] 提交当前状态（安全检查点）
- [ ] 文档化当前行为

### 第2阶段：确定改进
- [ ] 识别代码异味（重复，复杂性）
- [ ] 查找违反SOLID原则的地方
- [ ] 查找不清晰的命名
- [ ] 识别缺失的抽象
- [ ] 列出需要的具体改进

### 第3阶段：计划重构步骤
- [ ] 分解成小的，安全的步骤
- [ ] 根据风险/影响优先
- [ ] 识别步骤之间的依赖关系
- [ ] 计划在整个过程中保持测试绿色
- [ ] 考虑分成多个提交

### 第4阶段：逐步重构
- [ ] 一次只做一个小小的改变
- [ ] 每次改变后运行测试
- [ ] 保持测试通过（总是绿色）
- [ ] 每次成功步骤后提交
- [ ] 如果测试失败，还原并调整方法

### 第5阶段：改进设计
- [ ] 提取方法/函数
- [ ] 删除重复（DRY）
- [ ] 改进命名（清晰）
- [ ] 简化复杂的条件语句
- [ ] 为清晰添加类型提示

### 第6阶段：质量验证
- [ ] 运行make检查（必须通过）
- [ ] 验证没有行为变化
- [ ] 检查性能没有降低
- [ ] 与tdd-reviewer代理审查
- [ ] 确保覆盖率维持

### 第7阶段：文档编写
- [ ] 更新文档字符串以改变接口
- [ ] 为复杂逻辑添加注释
- [ ] 文档化为什么需要重构
- [ ] 如果适用，更新架构文档
- [ ] 记录设计决策

文档模板

文件： templates/documentation.md

### 第1阶段：内容审计
- [ ] 审查现有文档
- [ ] 识别过时的内容
- [ ] 查找缺失的文档
- [ ] 检查断开的链接
- [ ] 审查用户反馈/问题

### 第2阶段：内容规划
- [ ] 定义文档范围
- [ ] 确定目标受众
- [ ] 计划文档结构
- [ ] 优先更新部分
- [ ] 收集所需的技术细节

### 第3阶段：编写/更新内容
- [ ] 编写清晰，简洁的内容
- [ ] 添加代码示例
- [ ] 包括使用场景
- [ ] 如果有帮助，添加图表/视觉
- [ ] 遵循文档风格指南

### 第4阶段：代码示例
- [ ] 确保所有代码示例工作
- [ ] 测试代码示例实际运行
- [ ] 向示例添加注释
- [ ] 展示基本和高级用法
- [ ] 包括错误处理示例

### 第5阶段：审查与润色
- [ ] 检查拼写和语法
- [ ] 验证技术准确性
- [ ] 确保一致的术语
- [ ] 检查格式和布局
- [ ] 验证所有链接工作

### 第6阶段：与代码同步
- [ ] 在代码中更新文档字符串
- [ ] 确保API文档与实现匹配
- [ ] 更新类型提示文档
- [ ] 同步版本号
- [ ] 更新变更日志

### 第7阶段：验证
- [ ] 让其他人审查
- [ ] 从零开始按照文档进行测试
- [ ] 在干净的环境中验证示例
- [ ] 检查文档正确渲染
- [ ] 如果相关，更新AI_DOCS

安全修复模板

文件： templates/security.md

### 第1阶段：漏洞评估
- [ ] 了解安全问题
- [ ] 评估严重性和影响
- [ ] 确定受影响的版本
- [ ] 检查是否被积极利用
- [ ] 审查安全通告

### 第2阶段：影响分析
- [ ] 确定所有受影响的代码路径
- [ ] 评估数据暴露风险
- [ ] 检查其他地方是否有类似问题
- [ ] 评估认证/授权影响
- [ ] 审查合规性影响

### 第3阶段：安全测试（TDD）
- [ ] 编写测试展示漏洞
- [ ] 测试应该失败（利用漏洞）
- [ ] 测试常见攻击向量
- [ ] 测试边界条件
- [ ] 文档化攻击场景

### 第4阶段：实施修复
- [ ] 应用最小权限原则
- [ ] 使用安全编码实践
- [ ] 验证所有输入
- [ ] 清理输出
- [ ] 如果适用，添加速率限制

### 第5阶段：安全加固
- [ ] 添加额外的安全检查
- [ ] 实施深度防御
- [ ] 添加安全日志
- [ ] 更新认证/授权
- [ ] 审查加密/哈希

### 第6阶段：安全测试
- [ ] 运行安全扫描（Bandit）
- [ ] 用恶意输入测试
- [ ] 验证认证工作
- [ ] 测试授权边界
- [ ] 检查信息泄露

### 第7阶段：安全审查
- [ ] 从安全角度审查
- [ ] 检查OWASP Top 10合规性
- [ ] 验证没有引入新漏洞
- [ ] 测试错误消息不泄露信息
- [ ] 文档化安全措施

### 第8阶段：质量与文档
- [ ] 运行make检查
- [ ] 更新安全文档
- [ ] 在代码中添加安全注释
- [ ] 文档化安全假设
- [ ] 如果需要，计划协调披露

工作原理

第1步：分析任务描述

提取关键词以确定任务类型：

功能指标：

“add”, “implement”, “create”, “build”, “new”
“feature”, “functionality”, “capability”

Bugfix指标：

“fix”, “bug”, “issue”, “error”, “broken”
“crash”, “fail”, “regression”

重构指标：

“refactor”, “improve”, “clean up”, “reorganize”
“simplify”, “optimize”, “restructure”

文档指标：

“document”, “docs”, “README”, “guide”
“explain”, “describe”, “instructions”

安全指标：

“security”, “vulnerability”, “exploit”, “CVE”
“authentication”, “authorization”, “XSS”, “SQL injection”

第2步：加载模板

从templates/目录中读取适当的模板：

# 加载模板文件
template_file=".claude/skills/session-template/templates/${template_type}.md"
cat "$template_file"

第3步：定制模板

使用任务特定的细节定制通用步骤：

# 通用模板：
- [ ] 审查代码库中的相关代码

# 定制为"Add OAuth2 authentication"：
- [ ] 审查相关的身份验证代码以进行OAuth2集成

第4步：应用于会话

使用ai-update-plan将项目添加到当前会话：

# 将每个阶段项目添加到计划
uv run ai-update-plan --add "Review related authentication code" --phase "Phase 1"
uv run ai-update-plan --add "Identify OAuth2 provider integration" --phase "Phase 1"
# ...等等

第5步：显示计划

显示带有进度跟踪的完整计划：

uv run ai-update-plan --show

与ai-update-plan集成

这项技能利用ai-update-plan的功能：

按阶段添加项目

# 添加到特定阶段
uv run ai-update-plan --add "Write OAuth2 tests" --phase "Phase 2"

应用后定制

# 将通用项目重命名为特定项目
uv run ai-update-plan --rename "Review related code" \
  --to "Review existing OAuth implementation"

# 移除不相关的项目
uv run ai-update-plan --remove "Add diagrams/visuals"

跟踪进度

# 勾选完成的项目
uv run ai-update-plan "Review related authentication code"

# 显示进度
uv run ai-update-plan --show

定制指南

创建自定义模板

在templates/中创建新的模板文件
遵循标准阶段结构
使用复选框格式- [ ]
将相关项目分组在阶段中
包括所有质量门

示例自定义模板：

### 第1阶段：API设计
- [ ] 定义API端点
- [ ] 文档化请求/响应格式
- [ ] 选择认证方法
- [ ] 计划速率限制策略
- [ ] 设计请求/响应架构
- [ ] 计划版本策略
- [ ] 设计请求/响应架构
- [ ] 计划速率限制

[...其余功能模板...]

模板变量

模板可以包括占位符：

- [ ] 审查{module_name}模块
- [ ] 测试{function_name}的各种输入
- [ ] 更新{doc_file}文档

技能将根据任务描述分析替换这些。

输出格式

应用模板后：

## 应用会话模板：功能开发

**模板：** feature.md
**任务：** 添加OAuth2认证
**添加项目：** 28

### 计划结构：
- 第1阶段：研究与设计（5个项目）
- 第2阶段：编写测试（5个项目）
- 第3阶段：实施（5个项目）
- 第4阶段：重构（5个项目）
- 第5阶段：质量检查（4个项目）
- 第6阶段：文档编写（3个项目）
- 第7阶段：最终审查（5个项目）

### 应用的定制：
- 替换"Review related code" → "Review existing authentication for OAuth2"
- 添加"Research OAuth2 providers (Google, GitHub, Auth0)"
- 添加"Test token refresh mechanism"
- 移除通用占位符项目

### 查看您的计划：
```bash
uv run ai-update-plan --show

开始工作：

从第1阶段开始，完成项目后勾选：

uv run ai-update-plan "Review existing authentication for OAuth2"

定制计划：

添加任务特定项目：

uv run ai-update-plan --add "Test SSO integration" --phase "Phase 2"

移除不相关的项目：

uv run ai-update-plan --remove "Generic item"


## 最佳实践

1. **尽早应用模板** - 开始会话时使用模板进行全面规划
2. **立即定制** - 调整通用项目以特定于您的任务
3. **移除不相关的步骤** - 不要保留不适用的项目
4. **添加缺失的步骤** - 模板是起点，不是福音
5. **跟踪进度** - 完成项目时勾选它们
6. **根据学习更新** - 根据发现调整计划

## 模板选择指南

**使用"feature"时：**
- 添加新的用户面向功能
- 构建新的API端点
- 创建新的模块/组件
- 添加新的配置选项

**使用"bugfix"时：**
- 修复报告的问题
- 解决测试失败
- 处理回归
- 修补安全漏洞（次要）

**使用"refactor"时：**
- 改进代码结构
- 降低复杂性
- 删除重复
- 现代化代码模式

**使用"documentation"时：**
- 更新README
- 编写API文档
- 创建使用指南
- 改进代码注释

**使用"security"时：**
- 修复CVEs
- 加固认证
- 处理OWASP问题
- 实施安全功能

## 高级功能

### 多模板应用

对于复杂任务，组合模板：

```bash
# 安全修复需要重构
apply security template
# 然后添加重构项目：
uv run ai-update-plan --add "Refactor auth module for clarity" --phase "Phase 9"

模板继承

创建扩展基础模板的专门模板：

<!-- templates/api-feature.md -->
<!-- 扩展feature.md，添加API特定项目 -->

### 第1阶段：API研究与设计
- [ ] 审查相关API端点
- [ ] 定义OpenAPI/Swagger规范
- [ ] 计划版本策略
- [ ] 设计请求/响应架构
- [ ] 计划速率限制

[...其余功能模板...]

条件部分

模板可以包括条件指导：

### 第X阶段：数据库更改（如果适用）
- [ ] 设计架构更改
- [ ] 编写迁移脚本
- [ ] 测试迁移回滚
- [ ] 更新ORM模型

*如果不需要数据库更改，请跳过此阶段*

与其他工具集成

与ai-start-task集成

# 会话开始时原子地应用模板
uv run ai-start-task "Add OAuth2 authentication" --template=feature

与TDD Reviewer集成

模板包括TDD特定阶段：

第2阶段：编写测试（TDD）
第5阶段：质量检查（包括tdd-reviewer）

与Quality Enforcer集成

模板包括质量门：

第5阶段：质量检查（make check）
第7阶段：最终审查（质量验证）

记住

模板是起点，不是严格要求：

为您的具体任务定制
添加缺失的项目，这些项目对您的情况是唯一的
移除不适用的项目
根据了解更多调整阶段

目标是结构化的灵活性 - 足够的结构以确保质量，足够的灵活性以适应现实。