用AI技能将代码分析文档工作自动化

发表于 2026-03-29 分类于 AI经验

在日常开发中，每次排查 Bug 后的文档记录工作往往是重复且耗时的。手动创建「问题分析 + 修复指南 + 代码片段」一套文档需要 10-15 分钟，而且格式难以统一。本文分享如何将这套重复性工作抽象为一个可复用的 AI 技能，将时间缩短至 1-2 分钟。

问题背景

在南沙项目物联网开发中，每次 Bug 排查完成后都需要生成标准化的分析文档：

1
2
3

问题分析.md      → 根因分析、影响范围、排查过程
修复指南.md      → 修复步骤、前后代码对比、测试清单
代码片段/*.md    → 关键代码片段

以一个月内排查的 3 个 Bug 为例：

Bug	问题类型	涉及文件数	手动文档耗时
个人月卡拒绝 404	接口路径错误	6	~12 分钟
月卡变更审批拒绝 404	审批状态判断错误	6	~12 分钟
月卡变更车位占用校验	逻辑错误	7	~15 分钟

[!tip] 痛点分析
这类文档工作有两个显著特点：一是流程固定，都是「问题分析 → 修复指南 → 代码片段」三件套；二是格式规范，需要统一的 frontmatter、callout、wikilinks 结构。高度模式化的工作，正是自动化的理想场景。

解决方案：创建 obsidian-code-analysis 技能

基于 Claude Code 的 Skill 机制，将代码分析文档的创建流程封装为一个可复用的技能。

技能设计

基本信息：

属性	值
技能名称	`obsidian-code-analysis`
存放路径	`C:\Users\张\.claude\skills\obsidian-code-analysis\`
触发条件	用户说「记录」「写到知识库」「保存分析」等

核心工作流

主智能体收集分析上下文
         ↓
   确定文档类型（Bug / Feature / Refactor / General）
         ↓
   启动子智能体创建文件
         ↓
   调用 obsidian-markdown 技能格式化
         ↓
   使用 obsidian-cli 创建文件
         ↓
   更新每日工作记录

手动vs自动流程对比
*图1：手动与自动文档创建流程对比

关键设计决策：

主从智能体分工：主智能体负责分析和收集上下文，子智能体负责所有文件创建。这样避免主上下文被大量写入操作污染。
obsidian-cli 优先：obsidian create 比 Write 工具更节省 token，且直接与 Obsidian 集成。
模板引用分离：模板放在 references/ 目录，子智能体按需读取，不占用 SKILL.md 本身的空间。

技能文件结构

obsidian-code-analysis/
├── SKILL.md                          # 主技能文件
│   ├── frontmatter（触发条件）
│   ├── 工作流步骤
│   ├── 子智能体 prompt 模板
│   └── obsidian-cli 快速参考
└── references/
    ├── bug-templates.md              # Bug 分析模板
    ├── feature-templates.md          # 功能设计模板
    └── refactor-templates.md         # 重构分析模板

技能架构图
图2：obsidian-code-analysis 技能文件结构

支持的文档类型：

类型	生成文件	说明
Bug	问题分析.md、修复指南.md、代码片段/*.md	包含根因分析、修复步骤、测试清单
Feature	需求分析.md、实现方案.md、代码片段/*.md	包含需求拆解、技术选型、接口设计
Refactor	重构分析.md、重构方案.md、代码片段/*.md	包含重构动机、影响范围、迁移计划

实战验证：车位占用校验 Bug

以「月卡变更车位占用校验 Bug」作为测试用例，验证技能的实际效果。

Bug 概要

[!bug] 问题描述
个人月卡变更固定车位时，新车位实际空闲，系统却提示「车位已经被占用」，导致无法提交变更申请。

排查发现 3 个 Bug：

Bug 1：change() 方法检查的是老车位而非新车位
Bug 2：DTO 缺少 newParkingSpotId 字段
Bug 3：新旧车位用同一 ID 查询

技能执行结果

使用 obsidian-code-analysis 技能自动生成了 7 个文件：

文件	状态	说明
问题分析.md	pass	frontmatter 正确、callout 格式正确、根因清晰
修复指南.md	pass	步骤完整、前后代码对比清晰、测试清单齐全
代码片段/change方法.md	pass	Bug 标注明确
代码片段/changePass方法.md	pass	修复逻辑清晰
代码片段/changeRefuse方法.md	pass	无需修改原因说明清晰
代码片段/DTO.md	pass	新增字段标注明确
每日日志	pass	正确追加了新记录

修复方案示例

以 change() 方法的修复为例，对比修复前后的关键差异：

修复前（错误）：

// 检查的是老车位，用错了ID
if(monthPersonal.getParkingSpotId()!=null){
    ParkSlotEntity spot = parkSlotService.getById(monthPersonal.getParkingSpotId());
    if(!spot.getUsingState().equals("1")){
        return R.data(500, null, "车位已经被占用");
    }
}

修复后（正确）：

// 检查新车位，使用 DTO 传入的新车位ID
Long newParkingSpotId = dto.getNewParkingSpotId();
if (newParkingSpotId == null) {
    return R.fail("缺少新车位ID");
}
ParkSlotEntity newSpot = parkSlotService.getById(newParkingSpotId);
if (!"1".equals(newSpot.getUsingState())) {
    return R.data(500, null, "新车位已经被占用");
}

效率对比

指标	手动操作	技能自动化	提升
文档创建时间	10-15 分钟	1-2 分钟	~85%
格式一致性	因人而异	100% 统一	-
wikilinks 交叉引用	容易遗漏	自动生成	-
错误率	较高	极低	-

经验总结

何时适合自动化

工作流程高度结构化、模式固定
重复执行频率高（每月多次）
涉及多个文件、需要统一格式

技能创建的关键

先分析再抽象：识别重复模式，确认自动化价值
单一日标：一个技能只做一件事，通过组合实现复杂流程
模板与逻辑分离：模板可独立维护，SKILL.md 保持精简
子智能体隔离：文件操作放到子智能体，保护主对话上下文

适用场景扩展

除了 Bug 分析，这个思路还适用于：

接口文档自动生成：根据代码注释生成 API 文档
代码审查报告：自动整理审查意见并格式化
周报/月报汇总：从分散的工作记录聚合总结

结语

AI 技能的本质是将人的工作方法论封装为可复用的工具。通过识别重复模式、抽象流程、创建技能，我们能让 AI 从「一次性的助手」变成「长期共事的专家」。文档工作的自动化只是开始，代码分析、架构设计、测试用例生成等环节都值得用同样的思路去探索。