free-claude-code这个名字乍看像是要教你绕过什么付费墙其实完全不是。它是我自己搭的一套AI辅助编码工作流的代号核心就一句话把我日常跟模型对话时反复做的那些琐事——复制项目上下文、写提示词模板、整理输出结果——全部变成本地命令让代码更自由地流动在项目本身和AI助手之间。这个项目能做的事往小里说是省去复制粘贴的体力活往大里说是让AI辅助编码从聊天式试用变成工程化复用。适合正在用AI写代码、又不想被对话窗口绑架的开发者参考。1. 项目定位与思路拆解为什么要把AI辅助编码做成一套本地工具链1.1 从复制粘贴到结构化复用free-claude-code到底想解决什么我见过太多开发者用AI辅助编码的方式包括几个月前的我自己开一个对话窗口把报错信息贴进去把相关代码贴进去等一版答案再手工搬回编辑器。这种聊天式试用模式有三个很明显的毛病上下文是断裂的模型看不到项目全貌回答经常是盲猜。比如你问帮我修一下这个函数模型连这个函数被谁调用、依赖什么模块都不知道给出来的方案自然经常是看起来对跑起来错。提示词是重复的每天都要重新解释本项目是什么语言、用什么框架、编码规范是什么、哪些目录不要动。同样的背景说明一周能写十遍。产物是易丢失的对话窗口一关刚才的修改建议就没了。想回看上次让AI做了啥只能翻聊天记录翻完还发现当时没把关键约束写进去。free-claude-code 就是冲着这三个毛病下手的。它把项目快照、任务描述、约束条件固化成文件把模型输出落盘成Markdown报告让每次AI辅助都有案底。我给它定的目标很简单在任何目录下敲一条命令就能拿到一份结构清晰的上下文包发给模型再敲一条命令就能把模型输出存成可回看的文件。1.2 方案选型为什么选了本地优先的轻量CLI而不是IDE插件或重型工作流框架做这个项目之前我把能想到的路子都过了一遍。IDE插件路线能力强但绑定编辑器。我平时在VS Code和终端里来回切换工具就得换插件插件之间还不互通。云端开发环境路线什么都好但项目数据要过一轮外部服务对多数公司项目来说审计不方便而且离线基本等于废掉。自建CLI加本地文件路线轻量、透明、任何编辑器都能用。核心逻辑就是一个Python包加上几个Shell别名就能跑起来。我最终选了第三条。理由是不绑架工具链。只要目录在不管用什么编辑器打开都能执行同样的命令可以纳入版本管理。配置文件、模板文件、输出报告全部是纯文本Git全都能管上下文和输出都留在本地。这在很多团队里是硬性要求代码片段可以出去但至少要留一份审计记录。早期我试过一个功能很全的工作流框架装完光是调通各种依赖就花了两天最后跑起来还是卡在一个老版本库上。后来我想明白了这类工具90%的需求其实就是扫描目录、拼字符串、调接口、写文件这四步。用Python标准库加一个请求库就能搞定真没必要引一堆框架进来。项目越简单越好维护越敢天天用。2. 核心功能拆解与关键设计上下文托管、任务模板、输出落盘2.1 模块划分与整体工作流四个目录定天下free-claude-code 的整个项目结构只有四个核心目录我称之为四件套prompts/存放角色提示词和任务模板。比如代码解释员、单测生成器、代码评审官每个角色是一个独立的文本文件。context/运行时生成的项目快照不进版本库。里面是当前目录的文件树、关键文件摘要、最近改动列表。tasks/用户自定义任务描述。比如我要让AI解释一下utils.py里cache相关的逻辑这就是一个任务。outputs/AI返回的结果落盘。按日期加时间戳命名方便回溯。整体工作流是四个命令fcc init初始化目录结构fcc collect扫描当前项目生成快照fcc run -t 任务名读取任务模板和快照组装提示词fcc run调用模型服务把返回结果写进 outputs/ 目录。这个流程最特别的地方是每一步的输出都是文件。快照是文件提示词是文件模型回答也是文件。每一步都可以打开检查、可以手工修改、可以随时复跑。我见过很多自动化工具一把梭从输入到输出全在内存里完成出问题的时候根本不知道卡在哪一环。而我的原则是工具越透明越敢在生产环境里用。2.2 提示词工程与上下文管理四层模板加动态裁剪提示词这件事看起来只是写几句话实际上决定了下游所有输出质量。free-claude-code 里我采用了四层模板结构系统层定义模型角色、输出格式、安全边界。比如你是一名资深Python后端工程师只输出可运行的代码和必要解释不允许虚构API。项目层描述项目语言、框架、依赖、目录结构、关键文件路径。这一层由 collect 命令自动生成。任务层描述具体要做什么。来自 tasks/ 里用户写的任务文件。约束层防止AI乱来。比如不要改动migrations目录不要删除公共工具函数。举个例子我的一个模板文件长这样[system] 你是一名资深Python后端工程师熟悉FastAPI和SQLAlchemy。 你的回答必须满足 1. 代码可以直接运行不输出伪代码 2. 每次修改给出diff说明 3. 如果不确定某个API是否存在明确说明并给出验证方法。 [project] 项目根目录{project_root} 技术栈Python 3.11 / FastAPI / SQLAlchemy / PostgreSQL 关键目录 - {root}/app/api路由层 - {root}/app/services业务逻辑层 - {root}/app/modelsORM模型 忽略目录.git, .venv, __pycache__, node_modules [task] {task_description} [constraints] - 不修改数据库迁移文件 - 公共工具函数修改前必须说明影响范围 - 输出格式先结论再代码最后是测试建议上下文窗口管理也有几个细节。collect 命令生成快照时我默认忽略常见依赖目录对大文件只取头部和尾部摘要文件树最大深度限制为4层。还写了一个简单的token估算函数在组装提示词之前做预算避免辛苦拼出来的上下文被模型截断。实践下来把快照控制在8000到12000个token之间是平衡信息量和质量的甜点区。3. 实操过程全记录从零搭起一套可用的 free-claude-code3.1 环境准备与初始化一个Python包加两个配置文件环境要求极低Python 3.9以上pip一个可用的模型API服务或本地模型服务。我用的是本地服务加一个在线备用服务两者兼容同一套请求格式切换只需要改配置。初始化之后目录长这样. ├── config.toml ├── prompts/ │ ├── reviewer.md │ ├── test_generator.md │ └── explainer.md ├── tasks/ │ └── example_task.md ├── context/ │ └── (运行时生成) ├── outputs/ │ └── (运行时生成) └── fcc_cli.pyconfig.toml 是我精心调过的一个文件每个字段都有讲究[model] service local # local 或 remote base_url http://127.0.0.1:11434/v1 temperature 0.2 # 编码任务尽量低减少随机性 max_tokens 4096 # 单次输出上限 [context] max_depth 4 # 文件树最大深度避免卷进整个依赖目录 max_file_size_kb 64 # 超过64KB的文件只做头尾摘要 truncate_len 2000 # 摘要时头部保留的字符数 ignore_dirs [.git, node_modules, .venv, __pycache__, dist, build] [output] dir outputs format markdown这里重点说明两个容易踩坑的参数max_depth控制扫描深度。太大会把整个虚拟环境都卷进来太小又丢失关键结构。实测4层能覆盖大多数中小型项目的核心代码布局。max_file_size_kb控制单文件处理方式。大型锁文件、生成的JS bundle文件全文塞进上下文纯属浪费窗口。超过阈值的文件只提取开头2000字符和末尾500字符足够让模型判断这是什么类型的文件大致逻辑是什么。3.2 核心实现扫描器、估算器、提示词拼装器核心代码我拆成三个文件scanner.py负责抓项目快照estimator.py负责token预算runner.py负责调用模型和落盘。这里放最关键的一段扫描逻辑import os from pathlib import Path IGNORE_DIRS {.git, node_modules, .venv, venv, __pycache__, dist, build} MAX_DEPTH 4 MAX_FILE_SIZE 64 * 1024 TRUNCATE_HEAD 2000 TRUNCATE_TAIL 500 def scan_tree(root: Path, depth: int 0): 递归扫描目录返回文件树和文件摘要。 if depth MAX_DEPTH: return [] items [] try: entries sorted(root.iterdir(), keylambda p: (p.is_file(), p.name.lower())) except PermissionError: return [] for entry in entries: if entry.name in IGNORE_DIRS: continue if entry.is_dir(): items.append({type: dir, path: str(entry.relative_to(root)), children: scan_tree(entry, depth 1)}) else: size entry.stat().st_size summary if size MAX_FILE_SIZE: summary entry.read_text(encodingutf-8, errorsignore)[:TRUNCATE_HEAD] else: with open(entry, r, encodingutf-8, errorsignore) as f: head f.read(TRUNCATE_HEAD) f.seek(max(0, size - TRUNCATE_TAIL)) tail f.read(TRUNCATE_TAIL) summary head \n...[已截断中部]...\n tail items.append({type: file, path: str(entry.relative_to(root)), size: size, summary: summary}) return items写这段代码时有几个取舍先判断目录跳过再判断文件大小。很多工具只忽略目录不检查文件大小结果把.pyc这类二进制文件也读进来输出全乱码。这里我先看扩展名和体积。用 pathlib 而不是字符串拼接路径。跨平台兼容性立刻解决Windows 和 Linux 从同一个仓库跑路径不会炸。大小文件区别对待。小文件全文提取大文件只取头尾。模型不需要看中间几千行的实现细节只要知道这个文件是干什么用的就够了。token估算器没什么高深的东西就是一个经验函数def estimate_tokens(text: str) - int: 粗估token数中文按每字约1.5token英文按每4字符1token保守取大。 chinese_chars sum(1 for c in text if \u4e00 c \u9fff) other_chars len(text) - chinese_chars return int(chinese_chars * 1.5 other_chars / 4) 10它不追求精确只用来在组装提示词前做一道超限拦截。如果估算结果超过目标模型上下文窗口的约70%我就提醒自己手动精简快照或者降低max_depth。3.3 接入日常开发环境终端别名与编辑器命令这个项目不要求你改变习惯。我日常在终端里配了几个别名用起来非常顺alias fccpython ~/tools/free-claude-code/fcc_cli.py alias fcfcc run -t然后配合编辑器里的自定义任务命令。比如在VS Code里我可以按一下快捷键触发终端-运行任务-运行 fcc把当前文件路径作为任务参数传进去。整个过程不需要离开编辑器。具体到日常使用场景我是这么跑的修一个bug先把bug现场的报错贴到 tasks/fix_bug.md然后执行fcc collect和fcc run -t fix_bug。模型会拿到完整项目快照而不是只有一小段报错。它能看到报错文件里引用了哪些类这些类在哪个模块定义依赖关系一目了然。给模块补单元测试任务模板里写明针对 app/services/payment.py 生成 pytest 测试覆盖成功、失败、超时三条路径。模型根据快照里的实际代码直接生成可运行的测试文件。做代码评审评审模板会要求模型先读快照里的文件树再重点读变更文件输出按阻塞问题/建议优化/风格问题三档分类的评审意见。跑完后所有输出自动存到 outputs/ 目录文件名带时间戳比如20250121_1030_review.md。一周下来回头看每天做了哪些AI辅助决策一目了然。4. 踩坑实录与排查技巧那些文档里不会告诉你的问题4.1 上下文窗口溢出与输出质量劣化这是我用得最久、踩得最深的一个坑。刚开始用的时候我喜欢把整个项目的文件树和十几个关键文件全部塞进快照结果模型开始出现前言不搭后语的症状给它列了十条约束它只遵守前两条让它输出JSON格式它输出解释加JSON混合体甚至有时候答案写到一半戛然而止。排查过程我先看outputs/里生成的报告发现提示词实际字符数已经接近2万估算token数大约在6000到7000。对一个上下文窗口只有8000的模型来说留给回答的空间已经非常窄。模型不是变笨了是被我塞进去的噪音挤掉了推理空间。解决方式有三步把max_depth从默认的5改成4去掉嵌套过深的目录把max_file_size_kb从128降到64超过64KB的文件一律只取头尾摘要在提交前看一眼estimate_tokens()的估算结果超过目标窗口的60%就手动砍内容。改完以后模型回答的完整度明显回升。我的经验值是快照部分控制在8000到12000个token总提示词不要超过模型窗口的70%这样才能给模型的推理和输出留下足够空间。4.2 依赖冲突与跨平台路径兼容项目跑了一段时间后有次在另一台Windows机器上clone下来一跑collect就报错。报错信息指向一个路径拼接的 os.path.join在Windows下把反斜杠混进了 Markdown 链接导致Editors渲染错乱。排查过程我先查了错误堆栈发现是str(entry.relative_to(root))在Windows下返回的是反斜杠路径。后来统一改成entry.relative_to(root).as_posix()强制转换成/分隔的正斜杠格式问题立刻消失。另外一次是在升级依赖库之后JSON解析开始报错。我当时的接口返回格式是纯文本但某次更新后自动变成了带markdown代码块包裹的格式解析器直接崩了。排查后我做了两件事一是把依赖版本锁定到具体要求requirements.txt里精确到小版本二是在解析层加了兼容逻辑自动剥掉代码块围栏再解析。这类问题特别适合放进自动化测试里我写了一个固定的回归用例每次改动后先跑一遍。4.3 常用参数速查表我把运维过程中调过的参数汇总成一张表方便按需调整参数默认值建议值说明max_depth43-5文件树扫描深度大项目建议降到3max_file_size_kb6432-128超过阈值的文件只做头尾摘要truncate_len20001500-3000大文件头部保留字符数中文项目可以小一些temperature0.20.1-0.4编码任务保持低值创意类任务可适当调高max_tokens40962048-8192单次输出上限根据模型能力设定ignore_dirs.git等按需增加常见依赖目录必备测试目录视情况加入每次调参数我都会在 outputs/ 里留一份当时的提示词快照。这样如果某天发现输出质量下降能回头对比是哪次参数调整引起的。这是我在这个项目上最有价值的习惯之一。5. 进阶玩法与扩展方向从个人工具到团队基建5.1 多项目并行与结果溯源因为所有输出都落盘而且文件名带时间戳多项目并行天然不会串扰。我现在的做法是给每个项目单独建一份 config.toml放在项目根目录下collect时优先读取本地配置读不到再回退到全局配置。还有一个我后来加上的细节每次run命令执行前会自动计算当前快照内容的哈希值写进输出文件的头部。这样就能精确知道这份AI输出是基于哪份项目快照生成的。如果项目代码改动很大但报告是旧的看到哈希不一致就能立刻发现。5.2 接上自动化测试与代码搜索做了一段时间后我开始给流程接自动化测试。做法是在run命令执行成功后自动触发一个钩子脚本# hooks/post_run.sh 示例 #!/usr/bin/env bash if [ -f $PROJECT_ROOT/tests/test_generated.py ]; then python -m pytest $PROJECT_ROOT/tests/test_generated.py --tbshort fi如果模型生成的测试文件存在就自动跑一遍把结果追加到本次任务报告末尾。这样每次AI辅助完我不用手动去验证测试结果直接跟着报告走。另一个值得扩展的方向是用AST工具优化快照质量。目前的快照是纯文本摘要模型能看出有哪些文件但看不出文件之间的调用关系。我计划下一步引入AST解析把入口函数、对外接口、依赖模块整理成结构化的调用图放进提示词的项目层。这样模型在面对改动这个函数会不会影响其他模块这类跨文件问题时能有更准确的判断依据。最后分享几个日常使用中的小经验。我每天固定用这套工具跑两件事早上一来先在当前要动的项目里执行一次collect让快照反映最新代码状态晚上收工前把outputs/里当天所有报告扫一遍把值得保留的内容摘回项目文档。踩过几次坑之后我最大的体会是这类工具的价值不在于让模型替你做决定而在于把让模型参与决策这件事变得可重复、可回看、可修正。保持模板精简、参数保守、输出强制落盘是目前我用下来最顺手的节奏。