Claude Code 自定义工具：创建专属工作小工具

每次都要重讲一遍，那就错了

月末你照例要把销售表变成报告：先解释列名，再说明要算什么，最后叮嘱别改原表。这次少说一句，出来的东西就换了个模样。与其把同一套要求背得滚瓜烂熟，不如让它变成一段程序，以后只运行、不解释。

一次对话解决一个问题，一件小工具解决的是一整类问题。写工具的人不必看懂代码，但必须说清它要干什么——说不清，代码写得再漂亮也是白搭。

动笔之前先答四个问题

问题	要答出什么	举例
输入	交给它什么，格式如何	一份四列的销售表
输出	它交出什么，放在哪	一份 .md 报告
规则	怎么算、怎么排序、怎么取舍	合计、完成率、前后三名
边界	哪些动作不许做	原文件只读，不改不删

四问里最容易漏掉的是边界。规则错了，最多结果难看；边界没写，可能把原始数据覆盖掉。所以无论多急，边界那一行都不能省。

还有一件小事值得先定：这件事多久做一次。一周一次以上才值得做成工具；一年两次，直接对话更快。

一段可以直接抄的需求描述

不要只说「帮我写个脚本」。按下面的骨架把四项填满，再补一句交付要求。

用 Python 写一个命令行小工具，只做一件事：把月度销售表变成报告。
输入：一份表格文件，列固定为 日期、区域、销售额、目标额。
输出：一份扩展名为 md 的文件，含总销售额、各区域完成率排名、三条观察。
规则：金额取整；完成率保留一位小数；缺数据的格子写「缺」。
约束：原表只读，不修改、不删除；结果写到单独的目录里。
交付：告诉我怎么装依赖、怎么运行，并给一条示例命令。

最后那句「交付」经常被忘。你不提，它可能只给代码不给运行方法，也可能附一大段无关的背景。想让需求更规整，可以套提示词写法的格式；不清楚工具在整条链路里的位置，先看什么是工具调用。

先用三行假数据试跑

真实表格里总有脏行：空单元格、重复日期、单位混着写。第一次就拿它跑，报错时你分不清是逻辑写错还是数据不干净。随手造三四行样本，先确认三件事：输出文件生成了没有、数字算得对不对、原文件有没有被动过。

第一遍通过，再加一行刁钻的：缺一列、日期写成斜杠、金额带货币符号。工具能给出合理结果或明确报错，才算能用。

报错时把现场一起贴回去

只说「运行不了」，等于让它猜。把三样东西一起给它：完整报错、你敲的命令、文件放在哪。

运行 monthly-tool --in 样本.csv 时报错了，全文如下：（原样粘贴） 脚本和样本都放在 D:\报表\ 下，依赖是按你给的命令装的。

它通常能直接定位。真正难查的是「不报错但结果不对」，这时把样本和实际输出一起发过去，让它对照规则逐条解释。

三个例子，看清「规则」要写到多细

同样是「整理文件」，规则写到什么程度，结果差很远。下面三种需求，可以直接拿去改：

按日期重命名。 说明日期可能出现的几种写法，以及找不到日期时怎么办：

「把文件夹里的文件按文件名里的日期重命名。日期可能是 20250101、2025-01-01、25.1.1 三种写法，统一成 2025-01-01。文件名里没有日期的保持原样，不要猜。重名时在后面加 -2，不要覆盖。」

模板批量填充。 说清模板里的占位符、数据从哪一列来、一个客户生成一个文件：

「读取 template.txt 和 data.csv。把模板里的 {姓名}、{日期}、{金额} 换成表里对应列的值，每行生成一个 txt，文件名用 邮件_姓名_日期.txt。表里缺值的行跳过，并在最后打印跳过了哪几行。」

内容统计。 明确统计口径和排除项：

「统计文件夹里所有 txt：每个文件的字数、全部文件合计字数、出现次数最多的二十个词。统计词频前去掉「的、了、是、在」这类虚词，英文按空格分词。结果写进 result.txt。」

三段需求的共同点：都写了输入从哪来、异常怎么处理、输出叫什么。规则里的「不要猜」「不要覆盖」「跳过并报告」这类句子，比功能描述更能决定工具好不好用。

验收：别只看它说跑通了

工具写完，模型通常会说「已完成」。这句话只代表代码写出来了，不代表结果对。前面的小样本只够确认主路径通不通，正式使用前再按顺序查四件事：

1. 产物是否落在你指定的路径和文件名上，而不是脚本的当前目录；
2. 抽两行手算，和结果对得上吗；
3. 源文件的修改时间有没有变化——变了就说明它动过原表；
4. 同一份输入连跑两次，结果是否一致。

第三项最容易被忽略。有的脚本为了省事会就地改写，第一次跑看不出来，第二次跑数据就歪了。第四项能抓出「追加而不是覆盖」这类毛病：第二次运行结果翻倍，说明它往旧文件里续写。

报错处理也有顺序。先看报错最后一行指向哪个文件、哪一行；再看你敲的命令和它给的示例是否一致；最后才怀疑代码逻辑。把这三样一起贴回去，比只说「报错了」快得多。

不适合做成工具的情况也要认得：只做一次的临时活、每次判断标准都不同的活、数据涉密不能离开指定环境的活。前两种直接用对话解决，第三种先问清数据能不能给模型看。想让工具遇到异常时停下来而不是硬跑，可以了解护栏的思路。

界面不是必需品

不习惯终端，可以让它加一个选文件、点按钮的窗口。但顺序别颠倒：先让命令行版本稳定跑上几周，再考虑加壳。功能一次只加一个，加完立刻试；同时加三样，出问题你分不清是谁的锅。

不管你加不加界面，都留一份用法说明，哪怕只有五行：怎么装、怎么跑、参数是什么意思、结果在哪。三个月后你只会记得「有个东西能出报告」，不会记得参数怎么拼。

工具跑顺之后，下一节把它升级成懂你背景的伙伴：打造专属 AI 伙伴。