企业官网建设流程全解析

“free-claude-code”这个短语，第一眼很容易被人误解成什么破解资源或灰色渠道。我一开始也只是把它当作一个随手敲下的仓库名，后来越用越觉得它其实概括了一套很正经的方法论：用智能体式编程工具，去写免费、开源、属于自己的代码，同时把成本压到最低。这里的“claude-code”我并不特指某一个商业产品，而是这类能在终端里直接读代码、改文件、跑测试的编程代理工具的代称。这套方法我在本地反复验证了几个月，陆陆续续做了几个小工具，其中一个图像批处理Demo已经可以日常使用。这篇文章会把我踩过的坑、摸出来的工作流、以及那些文档里不会写明白的细节完整复盘出来，如果你也想走“AI辅助写开源代码”这条路，应该能少走不少弯路。

1. 为什么我把项目起名叫 free-claude-code

1.1 从“写代码的隐性成本”说起

过去用大模型写代码，大家第一个反应是 API 调用费，第二个反应是订阅费。但实际上最大的隐性成本不是钱，而是上下文管理成本——你让 AI 改一个函数，它往往会把整个项目都忘掉，改完 A 处弄坏 B 处，你又要花大量时间修。尤其是做开源项目的时候，功能不复杂，烦的是琐碎：目录怎么建、文件名怎么统一、异常怎么处理、文档怎么补。这些琐碎工作让 AI 来做非常合适，但如果工具选不对，你会发现大部分时间花在“反复解释需求”而不是“写代码”。

free-claude-code 这个名字，一开始就是我对这种状态的吐槽：我想要的是“免费的、随手可用的编程代理”，而不是一个需要小心翼翼伺候的聊天窗口。后来我意识到，真正该做的不是找到某个“免费版”工具，而是构建一套属于自己的工作流，让编程代理在最小成本下发挥最大价值。

1.2 这套方法到底解决了什么问题

我手上有个图像批处理需求：批量生成缩略图、清理图片里的私有信息、统一改文件名。这类需求并不复杂，用脚本写也就是两三百行，但非常零碎。我一开始直接在聊天窗口里让 AI 生成一个完整脚本，结果它给我输出了一段逻辑上成立、实际上跑不通的代码——问题出在图片编码格式判断上，它把我没告诉它的环境细节猜错了。

后来我把这个问题抽象成一整套流程：需求拆解 → 任务定义 → 代理解码 → 人工审查 → 自动化测试。每个环节都有一套简单约定，AI 只负责它擅长的“单点实现”，我负责它不擅长的“全局判断”。这套流程现在我命名为 free-claude-code，它不是某个软件，而是一套方法论加一组目录模板，你可以直接复制到自己项目里用。

1.3 适合谁看，不适合谁看

如果你是独立开发者，想用 AI 做点开源小工具；或者你在一个小团队，想让 AI 承担重复的模板代码、脚本开发；又或者你只是好奇“编程代理到底能干活到什么程度”，那这篇文章应该对你有用。反过来，如果你期待“一键生成整个商业项目”“零人工审查全自动开发”，那还是别抱这个幻想，至少现阶段不行。AI 编程代理更像一个执行力很强的实习生，而不是架构师；你能把需求说得多清楚，它就能把活干得多明白。

2. 核心工具链与工程目录设计

2.1 为什么必须选“智能体式工具”而不是普通聊天窗

这是整套方法里最关键的一个选择。普通聊天窗口型 AI 只能给你“一段代码”，你得自己复制到项目里，自己建目录，自己跑，报错了再把错误贴回去循环。而智能体式编程工具（也就是标题里 claude-code 指代的那类东西）能直接访问文件系统、执行命令、读取测试结果，它会自己去翻项目结构、定位相关函数、修改完再跑一遍测试给你看。

我做个类比你就明白了：普通聊天窗口就像一个远程顾问，他给你提建议，但活都得你自己干；编程代理就像一个坐在你工位旁边的实习生，你给他安排任务，他直接动手改代码，改完告诉你他改了哪里，你再检查。两者的效率差距，在项目小的时候不明显，一旦涉及跨文件修改，差距可能是 5 到 10 倍。

我用的是终端里跑的这类工具，纯命令行操作，没有图形界面。好处是适合脚本化、适合放进 CI 流程、也适合远程开发；缺点是新人上手需要一点终端基础。如果你完全没碰过终端，第一步要先补充命令行常识，否则会用得很痛苦。

2.2 一套可以直接抄的目录结构

我不喜欢每次开新项目就把整个提示词体系重新搭一遍。经过几次迭代，我固定下来一套模板结构，你直接复制过去就能用：

free-claude-code/ ├── specs/ # 需求说明书，每次只写一个任务 │ ├── specs-001.md │ └── specs-002.md ├── tasks/ # 拆解后的原子任务，每个任务一个文件 │ ├── task-001-ocr.md │ └── task-002-exif.md ├── agents/ # 给编程代理看的规则和提示词 │ ├── system.md │ └── review-rules.md ├── src/ # 实际代码 ├── tests/ # 测试代码 └── scripts/ # 自动化小脚本

这个结构的核心思想是：不要用地毯式的大提示词，而要用“任务文件”驱动。每个任务文件里写清楚背景、目标、约束、验收标准。这样有三个好处。第一，单次任务上下文干净，AI 不容易被无关信息干扰；第二，任务可以做版本管理，git diff 能看出需求本身的变化；第三，即使换一个编程代理工具，这套任务体系也能平滑迁移。

2.3 规则文件：编程代理的“次元边界”

编程代理能力再强，如果没有约束也会跑偏。我通常会在项目根目录放一个规则文件，内容不是功能需求，而是行为约束。比如：

- 修改代码前先解释影响范围 - 优先使用标准库，不引入额外框架 - 所有函数都要写一行注释 - 不自动执行 git commit，只提交待审查的 diff - 修改涉及外部接口时，必须同步更新对应测试

这不是空话，而是实打实的效率工具。因为编程代理的执行习惯太“外向”了，你不约束它，它会自作主张帮你装依赖、改配置、甚至重写你不希望动的模块。有了规则文件之后，它的行为会收敛很多，审查代码时也省力不少。我强烈建议第一次用时先花 30 分钟把规则文件写好，后面省下的时间远不止 30 分钟。

3. 实战：用 free-claude-code 流程做一个图像批处理 Demo

3.1 第一步：把需求翻译成“可验收清单”

这步是整个流程中最重要的一环，也是最容易被忽略的一环。很多人让 AI 写代码，只丢一句“帮我写一个图像批处理工具”，然后就开始抱怨 AI 写的东西不好用。问题不在 AI，而在需求本身。我把需求写成验收清单，让每个描述都是可测的。

以我那个图像批处理 Demo 为例，验收清单长这样：

功能：批量缩略图 + 文件名规范化 + EXIF 数据清理 输入：任意目录下的 jpg/png 图片 输出：指定输出目录，文件名统一为 yyyyMMdd_HHmmss.jpg 约束： 1. 输入的原始文件不得被修改 2. 缩略图最长边不超过 1024 像素 3. EXIF 数据必须被完整剥离，不能只清部分字段 4. 文件名重复时自动加后缀 _1, _2

写验收清单的过程，本身就是把“含糊想法”变成“明确规格”的过程。你会发现很多细节是在写清单时才想到的：比如“不修改原文件”“文件名冲突怎么处理”“EXIF 剥离程度”。AI 的任务不是替你想这些，而是帮你把这些规格翻译成代码。你越是把思考前置，AI 的产出越精确。

3.2 第二步：把清单拆成原子任务

一个大清单直接丢给编程代理，它通常会一次性产出一大坨代码，后面审查非常痛苦。我的做法是把功能拆成 3 到 5 个原子任务，每个任务只改一个点。比如图像批处理 Demo，我拆成了：

1. 读取目录下所有图片，过滤非图片文件，返回文件列表。
2. 对单个图片做格式判断与缩略图生成，输出到指定目录。
3. 实现文件名规范化与冲突处理。
4. 实现 EXIF 数据剥离。
5. 把所有步骤串联成批处理入口，补上简单测试。

每次只给代理一个任务文件，让它只关注这一件事。任务文件里我会附上相关代码的路径、已有的函数签名、以及测试方式。这样代理不会试图重写所有东西，更容易给出小而准的修改。这一步的本质，是把“一个复杂的整体”降维成“多个简单的问题”，AI 在简单问题上表现得远比复杂问题上可靠。

3.3 第三步：让代理动手，然后认真审查 diff

在终端里跑起代理，让它读任务文件，然后我会观察它的“执行计划”。这一步很关键，我一般会看两点：第一，它有没有先解释影响范围；第二，它有没有擅自改动任务之外的内容。

比如有一次代理在实现缩略图生成时，顺手把图片旋转逻辑也改了，理由是“发现 EXIF 里有 orientation 字段，顺便处理了一下”。听着很贴心对吧？但它改完之后，我的其他测试挂了。这就是典型的“超出任务范围的操作”。所以我通常在接受任何改动前，先让代理把改动汇总成一句话，我再决定要不要照单全收。审查 diff 的时候重点看三样东西：

• 有没有无关文件的改动（违规）
• 有没有硬编码路径（迟早出问题）
• 有没有明显的边界遗漏（比如空目录、损坏图片）

审查通过后，我才允许它跑测试。如果测试不通过，它自己继续迭代；如果通过了，我会再手动跑一个真实场景验证。不要省掉这一步，我见过太多“测试通过但实际不能用”的案例。

3.4 第四步：测试不是点缀，而是安全网

很多人让 AI 写脚本，写完能跑就完事了，不写测试。但如果你的代码以后还要继续演进，没有测试就是给自己埋雷。我在图像批处理 Demo 里写了一个很小的测试集，覆盖几个典型场景：空目录、含子目录的图片、损坏图片、文件名冲突。

一个简单的测试示例大概长这样：

def test_duplicate_filename_suffix(): files = ["a.jpg", "a.jpg"] result = normalize_filenames(files) assert result == ["a.jpg", "a_1.jpg"]

这类测试代码很朴素，但价值极大。每次改代码之后跑一遍，能立刻发现回归问题。我还会在任务文件里明确写一句“必须在 tests 目录下新增对应测试”，让代理自己养成写测试的习惯。测试是对代理产出最重要的护栏，也是你敢于让它持续改代码的底气。

4. 遇到的高频问题与排查实录

4.1 上下文太长，代理“忘了”后面的任务要求

这是最常遇到的问题。任务文件写得很详细，但代理执行到一半就“失忆”了，开始凭想象补逻辑。我发现大部分情况下不是工具不行，而是任务文件太长了，或者夹杂了太多无关背景。解决方法是把任务文件控制在 10 到 20 行以内，背景信息单独放在 references 目录里，不要让代理一次性读太多东西。

另一个有效的做法是把约束条件写在文件最前面，甚至重复强调一次。代理在读长文本时，对开头和结尾的内容记忆最清楚，中间内容容易被稀释。所以我通常把文件的最后一行写成“完成以上要求后，运行 tests/test_batch.py 确认全部通过”，提醒它闭环。

4.2 “能跑”和“正确”是两个世界

经历过几次惨痛教训之后，我总结出一条：代理给你的代码“能跑”不代表“正确”。有一次它生成的代码确实输出了缩略图，但输出的图片颜色和原图不一致，查了半天才发现它用了错误的颜色空间转换。程序没有报错，运行很流畅，结果却是错的。

这类问题很难靠代理自查发现，因为从它的视角看“代码逻辑没问题”。所以我一般会设计一个“黄金测试用例”：拿一张已知效果的图去验证输出是否符合预期。比如用一张纯红色的图片生成缩略图，然后检查像素值是否仍然是红色。只有针对特定功能设置人工观察点，才能把正确性问题暴露出来。

4.3 代理在循环里反复失败

还有一种让人抓狂的情况：代理修改代码后测试还是失败，于是它又改，改完又失败，陷入死循环。通常这种循环意味着它没有找到真正的根因。我见过很多次，它在同一个函数里绕来绕去，其实问题出在另一个文件。

这时候我一般会介入，叫停它。不是继续让它猜，而是先用 git diff 或反向查看日志，把最新的改动还原掉，然后给它一个更具指向性的提示。比如告诉它：“测试失败的原因是输入文件路径没有做绝对路径转换，请检查 src/batch.py 的 resolve_path 函数，而不是改 encode 模块。”一个准确的线索抵得上十次盲目迭代。

4.4 免费额度用得非常快，怎么控制

如果你用的是带免费额度的服务，很容易发现额度烧得比想象中快。最大的浪费来自无效往返：代理改了一行代码，跑失败，又改，又失败，一次任务能烧掉几十轮。控制手段就是我在第 2 节说的：小任务、短上下文、严格验收清单。任务越小，上下文越短，每一轮调用的有效性就越高。

另外一个实践心得是：不要在晚间人少的时候一次丢几十个任务让它通宵跑。因为一旦中间跑偏，后面全是垃圾产出，白白消耗额度。我通常是一次只交一个任务，跑完验收成功后再交下一个。看上去效率低，但整体成功率反而更高，成本也更低。

5. 开源发布前的合规检查与经验总结

5.1 开源许可证的坑

用 free-claude-code 这类流程写出来的代码，如果要公开发布，第一件事就是定许可证。很多人随便复制一个 MIT 模板就完了，但这里有两个容易被忽略的点。第一，AI 生成的代码用什么许可证。目前大部分主流工具并不会让用户拥有特殊版权，但我不会在这里展开具体的法律条款，因为不同地区、不同平台的规则会有差异。我的建议是：发布前自己读一遍许可证原文，别只凭网上的二手解释。

5.2 敏感信息与依赖审计

AI 生成代码时有一个隐藏风险：它可能会在测试用例或文档里留下一段真实的 API Key、私钥或者内部路径。这些往往不是它故意生成的，而是训练数据里带出来的“记忆残留”。所以我每次准备开源发布前，都会做一次全目录扫描，把常见的密钥模式、邮箱、 IP 地址全扫一遍。

还有依赖审计：编程代理经常建议引入各种第三方包，有些包其实完全可以用标准库替代。每多一个依赖，就多一个安全风险和包管理负担。我的规则是：优先标准库，其次少而精的第三方库，绝不为了偷懒加一堆工具库。

5.3 我踩过几次坑后的最终体会

做了差不多两个月之后，我对 free-claude-code 的体会已经变了：它最有价值的部分并不是“让 AI 替我写代码”，而是倒逼我学会把需求描述得越来越精确。过去我写代码经常会边写边改，需求模模糊糊就开工；现在不行了，因为如果你不清楚要让 AI 做什么，它就会自作聪明帮你决定，而自作聪明才是最大的麻烦。

有一次我让代理做图像去重，没说清楚“以内容哈希为准还是以文件大小为准”，结果它实现成了文件大小对比，导致大量重复图没被识别出来。这个锅完全在我，不在它。从那以后，我在每个任务文件顶部固定加一段话：“如果需求描述里有歧义，先列出所有可能解释并选择最保守的那个，然后问我确认。” 这条规则极大地降低了代理“过度解读”的概率。

再说一个小技巧：给代理起一个名字。听起来有点玄学，但我发现给它一个固定身份指代，比如“在项目里统一叫它 dev”，然后在规则文件和任务文件里都用这个名字来指代它，并反复强调“dev 只负责实现，不做决策”。这样对话和指令会清晰很多，它不会每次切换语气和立场。这个做法你也可以试试，成本为零，效果却很实在。

如果你也想开始自己的 free-claude-code 实践，不用等到万事俱备。先挑一个你真正需要的小脚本，按我说的四步走：写验收清单、拆原子任务、让代理实现、补最少限度的测试。可能前两次会感觉很别扭，但坚持两三个任务之后，你就会慢慢适应这种“人定方向、AI 搬砖”的协作节奏，并且很难再回到原来那种低效状态。这套方法目前还在我手里不断迭代，下一步我打算把任务文件的版本管理和多模块联动做得更自动化。如果你在实践中踩到比我更精彩的坑，欢迎拿着具体场景来一起讨论。