structured-development - SKILL.md Agent Skill

name: structured-development description: 定义完整的结构化开发流程，包括预研、计划、开发、测试、复查、报告等阶段。所有开发工作必须严格按照此流程执行。

结构化开发流程 (Structured Development Process)

此 skill 定义了严格的软件开发流程，所有开发任务必须按照此流程执行，确保代码质量和项目稳定性。

📋 流程概述

完整的开发流程包含以下阶段：

预研阶段 - 方案预研与分析
评估阶段 - 等待用户评估预研方案
计划阶段 - 制定详细开发计划
开发阶段 - 按计划逐步开发
测试阶段 - 单元测试、集成测试、系统测试
整理阶段 - 整理开发流程和内容
复查阶段 - 二次检测残留问题和新问题
修复阶段 - 如有问题，修复并重新测试
迭代阶段 - 继续检查直到无问题
报告阶段 - 生成完整报告并汇报

📖 详细流程说明

阶段 1: 预研阶段（方案预研）

目标: 在动手开发前，充分理解问题并设计解决方案。

执行步骤:

问题分析
- 明确需求是什么
- 分析当前代码状态
- 识别技术难点和风险
方案设计
- 设计技术方案
- 考虑多种实现方案
- 评估各方案的优劣
- 推荐最优方案
影响评估
- 分析对现有代码的影响
- 评估可能引入的风险
- 制定风险应对策略
生成预研文档
- 创建 docs/FEATURE_NAME_预研报告.md
- 包含：问题分析、方案设计、影响评估、推荐方案

输出: 预研方案文档

阶段 2: 评估阶段（等待用户评估）

目标: 获得用户对预研方案的批准。

执行步骤:

向用户展示预研方案
等待用户评估和反馈
根据用户反馈调整方案（如需要）

重要: ⚠️ 在用户批准预研方案之前，不得进行任何开发工作！

阶段 3: 计划阶段（制定开发计划）

目标: 将方案转化为可执行的开发计划。

执行步骤:

任务分解
- 将功能分解为具体的任务
- 确定任务依赖关系
- 估算每个任务的工作量
制定步骤
- 明确每个步骤的具体操作
- 确定每个步骤的验收标准
- 识别关键路径
生成开发计划
- 创建 docs/FEATURE_NAME_开发计划.md
- 包含：任务列表、步骤说明、验收标准、测试计划

输出: 开发计划文档

阶段 4: 开发阶段（按计划开发）

目标: 按照开发计划逐步实现功能。

执行步骤:

严格按计划执行
- 每次只处理一个步骤
- 完成当前步骤后再进入下一步
- 记录每个步骤的执行情况
代码质量
- 遵循项目代码规范
- 保持代码简洁清晰
- 添加必要的注释
开发日志
- 记录每个步骤的修改
- 记录遇到的问题和解决方案
- 保存到开发计划文档中

输出: 完成的代码 + 开发日志

阶段 5: 测试阶段（多层次测试）

目标: 确保代码质量，及早发现问题。

执行步骤:

单元测试
- 为每个新函数编写单元测试
- 确保测试覆盖率达到要求
- 运行：go test ./path/to/package
集成测试
- 测试模块间的交互
- 验证接口正确性
- 运行：go test ./test/integration/...
系统测试
- 测试完整的功能流程
- 验证非功能需求（性能、安全性等）
- 进行端到端测试
回归测试
- 运行所有现有测试
- 确保没有破坏现有功能
- 运行：go test ./...
编译验证 ⚠️ 新增
- 必须验证项目整体编译成功！
- 运行项目编译命令
- 检查所有模块是否编译通过
- 验证无编译错误、无警告
- 运行：
```
# Go 项目整体编译
go build ./...

# 或项目特定的编译命令
# 例如：go build -o nemesisbot.exe ./nemesisbot
```

验收标准:

✅ 所有测试通过
✅ 项目整体编译成功
✅ 无编译错误和警告

输出: 测试报告

阶段 6: 整理阶段（整理开发内容）

目标: 归档开发过程，方便后续查阅。

执行步骤:

整理代码变更
- 列出所有修改的文件
- 说明每个文件的变更内容
整理开发过程
- 记录开发中的关键决策
- 记录遇到的问题和解决方案
- 记录重要经验教训
更新文档
- 更新相关技术文档
- 更新 API 文档（如需要）
- 更新用户文档（如需要）
保存整理文档
- 创建 docs/FEATURE_NAME_开发整理.md
- 包含：代码变更清单、开发过程、文档更新

输出: 开发整理文档

阶段 7: 复查阶段（二次检测）

目标: 发现残留问题和引入的新问题。

执行步骤:

残留问题检测
- 检查是否有未完成的功能
- 检查是否有临时代码未清理
- 检查是否有 TODO/FIXME 未处理
新问题检测
- 代码审查：检查代码质量
- 安全审查：检查安全漏洞
- 性能审查：检查性能问题
- 并发审查：检查并发安全问题
生成复查报告
- 记录发现的问题
- 评估问题严重程度
- 创建问题清单

输出: 复查报告（包含问题清单）

阶段 8: 修复阶段（如有问题）

目标: 修复发现的问题。

执行步骤:

问题修复
- 按优先级修复问题
- 对每个问题进行根因分析
- 实施修复方案
回归测试
- 重新运行所有测试
- 确保修复没有引入新问题
- 验证问题确实被解决

重要: 修复后必须重新测试！

输出: 修复的代码 + 测试结果

阶段 9: 迭代阶段（继续检查）

目标: 持续改进，直到没有问题。

执行步骤:

重新复查
- 回到阶段 7
- 再次进行残留问题检测
- 再次进行新问题检测
判断
- 如果发现问题 → 回到阶段 8 修复
- 如果没有问题 → 进入阶段 10

重要: 此循环持续直到没有问题为止！

阶段 10: 报告阶段（生成最终报告）

目标: 向用户汇报完整开发过程。

执行步骤:

汇总所有信息
- 预研方案
- 开发计划
- 代码变更
- 测试结果
- 复查结果
- 修复记录
生成最终报告
- 创建 docs/FEATURE_NAME_最终报告.md
- 包含：问题背景、解决方案、实施过程、测试结果、问题修复、最终状态
向用户汇报
- 总结开发成果
- 报告测试结果
- 说明已知问题（如有）
- 提出后续建议

输出: 最终报告 + 汇报给用户

📝 文档规范

文档命名规范

预研报告：docs/FEATURE_NAME_预研报告.md
开发计划：docs/FEATURE_NAME_开发计划.md
开发整理：docs/FEATURE_NAME_开发整理.md
最终报告：docs/FEATURE_NAME_最终报告.md

文档内容规范

每个文档应包含：

头部信息
- 文档标题
- 创建日期
- 创建人
- 版本号
章节结构
- 清晰的章节划分
- 使用 Markdown 格式
- 包含必要的表格和代码示例
状态标记
- ✅ 已完成
- ⏳ 进行中
- ❌ 未完成
- ⚠️ 需要注意

🧪 测试文件规范

测试目录结构

所有测试文件必须放在 test/ 目录下，按照模块层级组织：

test/
├── unit/                    # 单元测试
│   ├── cluster/            # cluster 模块的单元测试
│   │   ├── cluster_test.go
│   │   ├── deadlock_fix_test.go
│   │   ├── p1_fixes_test.go
│   │   ├── handlers/       # handlers 子包的测试
│   │   │   ├── default_test.go
│   │   │   ├── custom_test.go
│   │   │   └── llm_test.go
│   │   └── rpc/            # rpc 子包的测试
│   │       └── llm_forward_handler_test.go
│   ├── channels/           # channels 模块的单元测试
│   └── config/             # config 模块的单元测试
└── integration/            # 集成测试
    ├── rpc/
    ├── channels/
    └── web/

测试文件命名规范

测试类型	文件命名	位置	示例
单元测试	`{module}_test.go`	`test/unit/{module}/`	`cluster_test.go`
功能测试	`{feature}_test.go`	`test/unit/{module}/`	`deadlock_fix_test.go`
集成测试	`{feature}_test.go`	`test/integration/{module}/`	`rpc_test.go`

测试文件组织原则

按模块层级
- 测试文件路径必须与源码模块路径对应
- 例如：module/cluster/handlers/ 的测试在 test/unit/cluster/handlers/
禁止混合放置
- ❌ 禁止在 module/ 目录下放置测试文件
- ✅ 必须将所有测试文件放在 test/ 目录下
测试文件包名
- 单元测试使用 {module}_test 包名
- 例如：package cluster_test
- 导入被测试的包：import "github.com/276793422/NemesisBot/module/cluster"

测试编写规范

Package 声明

// ✅ 正确：使用 _test 后缀
package cluster_test

import (
    "github.com/276793422/NemesisBot/module/cluster"
)

访问私有成员
- 测试文件在外部包，无法直接访问私有成员
- 使用公开接口进行测试
- 或添加测试辅助函数

测试文件示例

package cluster_test

import (
    "testing"
    "github.com/276793422/NemesisBot/module/cluster"
)

func TestClusterStart(t *testing.T) {
    c, err := cluster.NewCluster(t.TempDir())
    if err != nil {
        t.Fatalf("Failed to create cluster: %v", err)
    }

    if err := c.Start(); err != nil {
        t.Fatalf("Failed to start cluster: %v", err)
    }

    c.Stop()
}

⚠️ 重要原则

必须遵守的原则

预研优先
- 不做预研，不做开发！
- 预研方案不批准，不做开发！
计划驱动
- 没有计划，不做开发！
- 严格按计划执行，不跳步骤！
测试为王
- 没有测试，不算完成！
- 测试不通过，不算完成！
质量第一
- 有问题必须修复！
- 不带问题进入下一阶段！
文档完整
- 没有文档，不算完成！
- 文档与代码保持一致！
编译验证 ⚠️ 新增
- 开发完成后必须保证项目整体编译成功！
- 修改代码后必须验证编译是否通过
- 删除方法或修改接口时，必须检查所有调用方
- 添加新方法时，必须更新依赖的调用代码
- 编译失败就是开发未完成！

编译验证步骤：

运行项目编译命令

# Go 项目
go build ./...

# 或项目特定的编译命令

检查编译输出
- ✅ 无错误：继续下一步
- ❌ 有错误：立即修复，重新编译
修复所有编译错误
重新验证编译直到成功

重要：只有编译成功，才能进入下一阶段！

禁止事项

❌ 禁止跳过预研直接开发 ❌ 禁止预研方案未批准就开始开发 ❌ 禁止没有开发计划就开始编码 ❌ 禁止跳过测试或测试不通过就进入下一阶段 ❌ 禁止发现问题不修复就进入下一阶段 ❌ 禁止没有文档就认为任务完成 ❌ 禁止编译失败就认为开发完成** ⚠️ 新增 ❌ 禁止删除方法后不检查调用方** ⚠️ 新增 ❌ 禁止修改接口后不更新依赖代码** ⚠️ 新增

🎯 使用指南

当用户要求开发新功能时

第一步: 告知用户将开始预研阶段
第二步: 进行问题分析和方案设计
第三步: 生成预研报告并提交用户评估
第四步: 等待用户批准
第五步: 批准后制定开发计划
第六步: 按计划逐步开发和测试
第七步: 复查和修复问题
第八步: 生成最终报告并汇报

示例对话

用户: 我需要你添加一个新功能，实现 XXX

助手: 收到。我将开始结构化开发流程。

📋 阶段 1: 预研阶段
我将进行问题分析和方案设计...
(进行预研工作)

✅ 预研完成

我已经完成了预研，生成了预研报告：
docs/XXX_FEATURE_预研报告.md

📊 预研方案摘要：
- 问题分析：...
- 推荐方案：...
- 风险评估：...

请评估此方案。批准后我将进入开发阶段。

用户: 方案批准，可以开始开发。

助手: 收到批准！

📋 阶段 3: 计划阶段
我将制定详细开发计划...
(制定计划)

✅ 开发计划完成

开发计划已保存到：
docs/XXX_FEATURE_开发计划.md

📋 阶段 4: 开发阶段
开始按计划执行开发...

📚 相关资源

项目根目录：C:\AI\NemesisBot\NemesisBot
文档目录：C:\AI\NemesisBot\NemesisBot\docs
测试目录：C:\AI\NemesisBot\NemesisBot\test

✅ 验收检查清单

在向用户汇报最终报告前，确认以下事项：

预研报告已完成并获得批准
开发计划已制定并保存
所有开发步骤按计划完成
单元测试全部通过
集成测试全部通过
系统测试全部通过
回归测试全部通过
项目整体编译成功 ⚠️ 新增
所有模块编译无错误 ⚠️ 新增
无未使用的导入或死代码 ⚠️ 新增
代码复查完成，无残留问题
新问题检测完成，无引入问题
发现的问题已全部修复
开发整理文档已完成
最终报告已完成
已向用户汇报

只有所有检查项都完成，开发任务才算真正完成！