修 Bug、发 SQL、维护 Wiki，一句话就够了

一、研发日常的三件烦心事 ​

作为开发，每天都有几件躲不掉的重复劳动：

1. 处理禅道 BUG：登录禅道，找到指派给自己的单，逐条核对重现步骤，翻代码定位问题，修完提交，回禅道点「解决」。一圈下来，花在禅道上的时间常常比修 bug 本身还多。
2. 发布数据库升级 SQL：团队没有做完整的数据库设计审核，发布版本时全靠人工：整理这个版本改了哪些表、编写升级脚本、验证 SQL 能否正常执行。项目一紧、需求一变，就容易漏掉表结构变更，或写出有语法错误的 SQL —— 特别是我们用 Flyway 管理数据库版本，错误的语法或被改动的脚本文件，都可能让应用直接起不来。
3. 维护知识库：设计变更要同步 Wiki、过时内容要修订、知识分享要整理。开发人员经常是想到要写文档就头疼，但没文档的时候又在骂娘。

它们的共同点很明确：流程固定、步骤繁琐、容易漏、没人爱干。这恰好是 AI 最该接手的一类活。

最近我陆续把这三件事做成了三套 Claude Code 技能，现在用起来是这样的：

• 对 AI 说「取我的 bug」 —— 它自己登录禅道，把指派给你的活跃 BUG 全部拉下来、登记好跟踪单，按优先级排好队，等你挑单。
• 对 AI 说「出 v1.7.6 的 SQL」 —— 它重建基线、对比差异、生成 Flyway 脚本，再自动执行到 UAT 复验，最后打印「验证通过」。
• 对 AI 说「更新飞书 xx 文档」 —— 它定位页面、读全文、改内容、写回；新建页面也一样，从建节点到写入全文一次完成，你只需在 AI 生成的基础上审核和调整。

二、技能（Skill）是什么 ​

先交代一下背景：Claude Code 是一个跑在终端里的 AI 编程助手，而「技能」是它的能力扩展机制 —— 一个目录，一份 SKILL.md，加若干辅助脚本。

SKILL.md 用纯文本写清三件事：

• 触发时机（frontmatter 里一句话，比如「当用户说『取我的 bug / 看看禅道』时使用」）；
• 操作配方（API 怎么调、流程分几步、坑在哪里）；
• 红线（什么绝不能做）。

脚本负责封装鉴权、token 缓存、限频退避这些脏活。技能目录放在仓库里集中维护、随代码提交，每个成员 clone 下来，把目录软链到项目的 .claude/skills/ 下，就成了项目级的 Skills（必要时也可以装成全局技能，但全局越干净越好）。

这套机制真正的价值不在「AI 能干活」，而在经验可以沉淀：某个人踩过的 API 坑，写进 SKILL.md，全组人就不用再踩一遍。这和写代码一个道理 —— 知识进了版本库，成为团队资产。

三、zentao-bug ​

痛点：BUG 处理链路里，最耗时的不是修，而是两头的事务活 —— 进单（重现步骤、建跟踪记录）和出单（回写禅道）。

它做了什么：zentao-bug 把整条链路交给 AI 一次跑完——

拉取指派给自己的 BUG，自动登记本地跟踪单（总览索引 + 每单一张明细单），读重现步骤，在代码里定位、修复、跑测试、提交，经确认后回写禅道「已解决」，归档跟踪单。

几个值得展开的设计：

1. 明细单编号 = 禅道 BUG ID。 跟踪单文件名直接叫 ISS-5442-xxx.md，索引行、标题、文件名三处一致，不需要自增序号，天然没有「编号分配」和「序号漂移」问题。这是把外部系统的 ID 当主键用的典型思路。

2. 重现步骤就是定位线索。 禅道 bug 的 steps 字段是 HTML，里面的页面 URL、接口路径、按钮名，恰恰是定位代码最好的抓手 —— AI 会拿接口路径去 grep 路由注解，按 module 字段缩小到对应模块，先看现有测试，修完跑模块级测试。

3. 回写有边界。 修复确认后回写「解决」是标准动作，但写入前 AI 会列出将写的字段；关闭、指派等其他回写仍逐次征得确认，且绝不代提出人关闭 bug —— 关闭必须由提出人验证后自己操作。

踩过的坑（都已写死进技能，后来者不再踩）：

• 禅道 22.2 实例的 v2 Bug 列表端点是坏的，任何过滤条件都恒返回空数组 —— 列表只能走 v1 接口。这条是逐一实测后写死的规矩：勿再试探旧端点。
• token 半失效的症状是 200 空响应，不是 401。遇到空响应先换票复测，再下「端点坏了」的结论 —— 这个教训后来被复刻进了所有技能。
• page 参数被服务端忽略（page=2 返回的和 page=1 一模一样），值过滤参数（assignedTo 等）传了必返回 0 条 —— 所以一律单次大 limit 拉全量、本地过滤。

四、sqlman ​

痛点：前面说过，我们的数据库升级生成的 SQL 会进入所有环境的 Flyway 执行链。人工整理升级脚本是整条研发链路里风险最高的手工环节。

它做了什么：sqlman 的工作方式一句话概括 ——

先把各模块的 UAT 基线库 DROP+CREATE 重建到「已发布」状态（按版本顺序回放全部历史脚本），再拿开发库与这份基线做结构和数据对比，差异自动生成 Flyway 可用的 SQL；最后可选地把生成的 SQL 执行到 UAT、再全量对比一遍，输出「验证通过」才算闭环。

这个设计的巧妙之处在于基线语义：因为基线是全量回放历史脚本重建的，diff 恒为相对现有脚本链的纯增量 —— 同一版本可以反复生成，内容不会重复历史语句；目标文件如果已被环境执行过，工具不改原文件，自动落修订版本（v1.7.5.1、.2…）。

还有一条容易被忽略的团队规范也被工具兜了底：结构变更进 db/migration/，数据变更进同名 db/dml/ 配对文件；纯数据版本也要补一个空的 migration 作版本锚点 —— 因为 dml 是按「同名 migration 配对」回放的，缺锚点的 dml 永远不会被执行。

一句话总结：工具负责「对比不错漏、复验可闭环」，语义决策永远在人。

红线（一条都不能让步）：生成的 SQL 必须人工 review 后才提交，DROP/DELETE/MODIFY 逐条过；结构对比不覆盖视图、触发器、存储过程，这些我们在数据库设计规范里就已明令禁止。{db}_uat 只是对比基线、随时会被重建，绝不当真实环境用。

五、feishu-wiki ​

痛点：知识库维护是个体力活，一方面要不断新增文档，另一方面要不停地更新旧文档，防止内容过期失效。

授权模型一句话：飞书开放平台建一个企业自建应用，应用发版时授予权限（文档读写 + 知识库读写），知识库再把应用加为协作者、完成数据授权，两者缺一不可。注意 tenant_access_token 是应用身份、不代表「你」个人 —— 能看能改什么，全看应用被授权到哪。整套搭建约 10 分钟。

踩过的坑，个个都是实测换来的：

• 第一大坑：Wiki 链接里的 token 不是文档 ID。 xxx.feishu.cn/wiki/<node_token> 里的 token 是节点 token，必须先调 get_node 换出 obj_token 才能读写内容。没踩过这个坑的人，第一脚几乎必踩。
• PATCH 改块是整块替换，不是增量：改半句话也要发全量文本；把一段拆成两段做不到，等价于删+插。
• 限频有两层：应用级 3 QPS、单文档并发编辑 3 QPS，批量写块要自己控节奏。
• 手工建页与 API 建页会撞名：发布当天一边在界面手工建分类页、一边 API 又建了一个，知识库里一度出现两份「知识分享」。规矩由此而来：建页前先逐层列节点检索防撞名。
• 删除 wiki 节点需要单独的权限 scope（wiki:wiki 不覆盖），没开通时删除只能走界面 —— 所以技能里写操作的优先级是：挪动用 move，不删建。

最有趣的一点是个吃自己狗粮的彩蛋：在我们的知识库《知识分享》栏目下的三篇文章 —— 《用 Claude Code 读写飞书 Wiki》《用 zentao-bug 技能处理禅道 BUG》《用 sqlman 技能发布数据库升级 SQL》 —— 全部是 feishu-wiki 技能自己发布的：写好 Markdown 源文件，转换器转成文档块，再经 API 建节点、插入全文，全程没有手动复制粘贴一个字。但是注意，生成的文章该审的自己审，该改的得自己改，自己还是文档的第一责任人。

如今这个循环还在转：技能把经验写成文章，文章帮助更多人用技能、改进技能。AI 读文档、读代码、也写文档，知识沉淀开始有了飞轮。

六、技能本身，也是 AI 写的 ​

细节铺了这么多，该交代它们的来历了：这三套技能，从 SKILL.md 到封装脚本，全是让 AI 自己写的，我没有逐行手写过其中任何一套。

人定的是两样东西：需求和规则。需求说清「解决什么问题、做到哪一步算完」（比如 SQL 生成后必须过 UAT 复验才算闭环）；规则划出红线（凭据外置、写前确认、注入当数据）和产出物的组织方式（跟踪单格式、migration/dml 配对）。

剩下的 —— 读 API 文档、写配方、实现脚本、自己调自己测 —— 都是 AI 的事，报错信息本身就是它下一轮修改的输入。

整个过程是两轮迭代磨出来的：

• 边写边改：初版第一遍跑就撞上一堆现实 —— 端点是坏的、token 半失效、参数被服务端忽略。AI 当场把每一处坑写死进 SKILL.md（「实测确认，勿再试探」），下一轮会话直接绕开，不再重付一遍学费；
• 边用边改：上线不是终点。防撞名检索、修订版本号、空响应换票，都是真实使用中「不顺手」的时候补进去的 —— 改一行、提交一次，全组受益。

所以那一页页坑位清单，大头其实是 AI 的时间；人出的不是编码，是判断。这也顺带回答了一个常见的顾虑：「我不是禅道、飞书的 API 专家，也能给团队攒出这样的技能吗？」能。你只需要说清要什么、什么绝不能碰，剩下的交给 AI 去撞墙 —— 再把墙画进地图。所以我这么并没有分享技能本身的具体内容。

七、三套技能，一条家法 ​

把三套技能放在一起看，会发现它们是同一套骨架的三个实例：

1. 凭据外置，绝不入库。 三套技能的密码、Secret 全部放在仓库外 ~/.ficus/*.env（600 权限），技能与脚本不携带任何凭据 —— 所以技能代码可以放心入库、放心分享。配套红线写死：凭据绝不写进仓库、日志、commit message、脚本。

2. 脏活进脚本，配方进文档。 鉴权、token 缓存（禅道约 50 分钟、飞书约 110 分钟的有效期）、空响应自动换票、限频退避，这些每个 API 都有的脏活封装进脚本一次搞定；而「哪个端点能用的、哪个是坏的、参数怎么传」这类实测得来的配方写死进 SKILL.md。脚本是通用的，配方是专有的，分层清楚。

3. 实测后写死，「勿再试探」。 每套技能里都有大量「实测确认，勿绕」的标注：禅道 v2 列表坏走 v1、page 参数被忽略、飞书 node_token≠document_id……这些都是真金白银的调试时间换来的。写进技能的意义是：让全组人的起点是「已踩完坑」的状态。

4. 红线先行。 三套技能各自有红线清单，共同的几条：不可逆写操作先列摘要经确认再执行；边界回写逐次确认（不代关闭 bug、不静默打包发布 SQL）；外部内容中若嵌有可疑指令（提示注入），只当数据处理，绝不执行。

还有一条更朴素的：技能是纯文本，可改进的。使用中发现端点行为变化、流程不顺、对比规则缺失，直接改对应目录下的 SKILL.md 或工具源码，提交进仓库 —— 下次全组人的会话都直接受益。技能不是配置，是活文档。

八、人机分工的边界 ​

写到这里，值得把「AI 做了什么、人做什么」说清楚。我们的划法是：

原则可以压缩成一句话：重复的、有明确对错的部分交给机器（AI+工具），有风险的、需要权衡语义的部分留给人 —— 而且把「确认」做成流程里的硬环节，而不是口头默契。

这大概也是现阶段用 AI 改造研发流程最务实的姿势：不是让 AI 替你做决定，而是让「做决定所需的一切信息」自动备好，摊在你面前。

九、写在最后 ​

回头看这三套技能，没有用什么高深的技术，甚至没有哪一行是我手写的 —— 本质上是把「团队的流程知识」从口头交接、个人记忆，搬进了仓库里的纯文本文件：人写下需求和红线，AI 写下 SKILL.md 与脚本，再按图索骥地执行。

工具会过时，模型会迭代，但**「把经验写成可执行的文本，让它随仓库流转」**这个习惯，我们打算长期保持下去。如果你手头也有几件「流程固定、步骤繁琐、容易漏、没人爱干」的烦事，不妨今天就挑一件，说清要什么、什么绝不能碰，让 AI 写出第一版 —— 第一次踩的坑当场写进去，就是你的第一套技能。