t3code 这名字老粉看到可能会愣一下是 T3 Stack 那套技术栈还是某个开源仓库我刚听说时也这么猜过。真正把它跑起来用了两周我现在的看法很直接t3code 是一个以整个仓库为工作对象的 AI 编码代理它和自动补全不是一个物种。它能自己读代码、改文件、跑测试、再迭代直到把任务做完。这篇文章不是官方文档的复述而是我把它塞进真实项目里的现场记录哪些配置值得花时间哪些坑我踩过了什么任务能放心交给它什么任务交给它第二天可能给你造出惊喜。我手上有两个业务系统一个 8 万行一个 20 万行另外还有几个一次性脚本项目。之前用逐行补全类工具感觉效率提升有限——它只给我补行不帮我理解整个模块。改一个跨了四五个文件的老接口该翻的代码一行都省不了。所以看到代理式的工作方式时我心里有两个问题它真能把小活直接干完吗它会不会在我不注意的时候把我仓库搞乱这两周里两个问题都有答案了。1. 为什么要把 t3code 放进日常开发流程1.1 它想解决的不只是补全代码先做一个类比补全工具像是输入法的联想你打一个字它猜下一个字t3code 更像是给一个上手快但粗心的小实习生布置任务。你给一个目标它自己会去翻资料、改草稿、跑一遍自检然后把结果拿来给你看。这个区别很重要因为它决定了你要用什么样的心态去用它——你不能像用补全工具那样一直盯着屏幕你只能在几个关键节点做验收。那它具体能做什么我在第一个测试项目一个小工具仓库里给了它三件事给一个老的 Python 模块补单元测试把散落在三个文件里的常量收敛到一个配置类里修掉 lint 配置升级后冒出来的一百多个告警。三件事都不难但都属于脏活累活逐个人工干至少要半天。t3code 处理这三件事先把每个文件打开、把符号关系搞清楚然后批量改改完还自己跑了一遍测试。我检查结果时发现质量比我预想的稳定但也发现它有几个固定的毛病后面专门开一节说。了解它的工作方式之后我真正想问的是它到底改变了开发流程里的哪个环节结论是理解成本。传统方式下改一处跨文件逻辑你要先在脑子里建立一张影响面图t3code 能替你把这步做了它给出的 diff 本身就是在展示它对影响面的判断。省下的时间可以用来做更重要的代码审查而不是花在找出所有调用点这种机械劳动上。1.2 尝试前的三个判断标准不是所有项目都适合立刻引入我试之前给自己定了三个条件仓库必须能随时回滚。git 工作区要干净分支要清楚任何一次 t3code 的改动都能一条命令退回。别在改动了一半的本地分支上直接让它开工否则它基于的基线是脏的出了问题你分不清哪些是它的错、哪些是你改到一半的烂摊子。有能跑的测试。哪怕是覆盖率很低的旧项目至少有一个 make test 或者 npm test 能一键执行的东西。没有这个保护网AI 跑得越快你事后排查越慢——它改坏的代码不会自己告诉你。任务结果可以被客观验证。比如补测试修 lint重命名这类有明确完成标准的任务相反让这个模块更优雅这种任务AI 会给你做出非常主观的改动你很难验收。我的测试仓库三个条件都满足所以我才敢让它放开手跑。如果你手头是个连 CI 都没有的历史遗留项目我强烈建议先把最小测试链路搭起来再考虑引入 t3code。这个顺序不能反。2. 首次跑通 t3code 的最小化配置2.1 环境准备与模型接入我第一版接入方式非常朴素一个干净的 Python 3.11 虚拟环境装好 t3code 的命令行入口然后在项目根目录放了一份模型接入的配置。它支持接入托管的模型服务也支持对接私有化模型端点我用的私有化端点原因很简单测试仓库里有一些内部业务的 schema我不想把表结构送去外部服务。这个考虑在多数公司项目里都成立。我的配置大概长这样路径和密钥做了脱敏处理T3_MODEL_ENDPOINThttps://内部网关/v1 T3_API_KEY**** T3_MODEL_NAMEqwen2.5-coder:32b T3_CONTEXT_POLICYrepo-aware这里最需要注意的是CONTEXT_POLICY。它决定了 t3code 会以多广的范围去理解仓库。我一开始用的默认策略它只看当前工作区附近几个文件遇到跨目录的引用就开始瞎猜改成 repo-aware 之后它会先建一次仓库索引后面每次动手前把相关文件一起拉进上下文准确率明显上了一个台阶。当然代价是慢第一次索引一个 8 万行的仓库在我的机器上跑了大概两分钟。这个时间值得花。如果你用的是云端模型注意把敏感信息和密钥管理好别直接用真实 key 写进脚本里。我见过有人把密钥直接打在配置里然后推到远端仓库这个失误比 t3code 本身容易出现。2.2 第一次派活任务描述怎么写把任务描述清楚是影响 t3code 输出质量的最大变量。我的第一个任务是这样写的任务目标为 src/legacy_payment.py 中的 PaymentProcessor 类补充单元测试。 验收标准 1. 覆盖 process() 的所有分支包括成功、余额不足、重复回调三种情况 2. 不修改业务代码只新增测试文件 3. 用 pytest 运行全部测试并通过 4. 不要改动 src/ 目录下任何文件。 约束如果发现测试需要 mock 数据库连接请仅 mock 在 tests/conftest.py 中声明。注意我做了什么给了文件路径、类名、验收标准、明确的禁止项、以及 mock 的处理位置。这里面第二条是最关键的——AI 编码代理有一个倾向就是为了让测试好写顺手去改业务代码如果不提前禁止它很可能给你返回一个全绿但已经悄悄重构过的仓库。我后来给团队总结了写任务的四要素做什么、在哪里做、怎样算完成、什么绝对不能做。四要素缺一个输出质量就会肉眼可见地下降。2.3 输出检查的第一站t3code 完成后我没有直接看测试结果而是先看 diff 的统计和摘要。这一步别省。一个几千行改动的差异第一眼就要判断它的改动范围是否合理。我那次任务它新增了一个测试文件同时真的没有碰 src/符合预期。接着我逐个看 diff 的关键片段重点关注 mock 是否写对、断言是否真的能生效。这里有个反直觉的点AI 生成的测试代码断言很容易写成恒真——比如 mock 了返回值之后又断言返回值等于那个 mock 值这种测试什么都不验证。我抓到过不止一次。所以测试类任务我会随机抽几个用例把 mock 值改成明显不合理的脏数据看断言会不会失败。不会失败说明这条断言大概率在自说自话。这样第一轮跑通之后我对 t3code 的使用方式就有了底气它可以干活但必须配合一套固定的验收流程。这比任何参数调优都重要。3. 真实项目里的 t3code 协作模式3.1 把边界划清楚哪些目录不归它管跑过测试项目后我把 t3code 引进了那个 20 万行的业务系统。进去之前我做的第一件事不是写任务而是划边界。业务系统里有一些目录AI 改不得数据库迁移脚本、支付相关的核心领域对象、以及部署配置。我不是不相信它而是这些目录一旦改错代价是线上事故级别不值得用AI 试一下去赌。t3code 支持在配置里声明可写目录和只读目录。我的配置是这样[permissions] allowed [src/, tests/, scripts/] read_only [src/main/java/com/company/payment/, db/migrations/, deploy/]这个设置效果非常直接它彻底断了 AI 在我最担心的区域动手的可能性同时在允许区域内它可以放心干。配置完之后我在 README 里给团队写了一句约定进 CI 的任务默认只能在允许目录内修改如果任务确实要碰只读目录必须显式在任务描述里说明理由走一遍人工确认。边界还有一个好处它可以帮你做影响面收敛。AI 编码代理默认是无边界的它不知道哪些文件碰不得只靠自然语言约束很容易漏。给它的文件系统权限加上物理上的限制比多写两行提示词靠谱得多。3.2 上下文管理仓库理解越深幻觉越少划线之后我用它做的第一个真实任务是重构一个订单状态的枚举。这个状态枚举散在六个文件里有的文件通过字符串比较有的通过常量引用还有一个老接口直接用了魔法值。我一开始试图用一段任务描述说清楚所有位置结果漏了那个用魔法值的文件t3code 改完之后那个文件的判断逻辑就断了。那次翻车让我意识到任务描述里写的位置总会有遗漏更好的办法是让 t3code 先建好仓库索引然后直接问它订单状态一共有哪几种引用方式。它会基于索引把引用点列出来我再拿这个列表核对比我自己回忆靠谱。从那以后我的工作方式变成了两段式先让它做一次侦察再开始正式任务。仓库理解深了之后幻觉的概率明显下降。之前它在不确定某个符号含义时会倾向于猜一个“看起来合理”的写法有了索引和上下文它更倾向于先查再答。代价是每次任务的启动时间变长但换来的是后期 review 时间大幅缩短。两相对比很划算。3.3 擅长 vs 不擅长的任务用了一个月我整理了一张任务类型对照表贴在团队文档里任务类型效果我的判断批量重命名、移动符号非常好可以自动补缺的单元测试好但断言需要抽检自动抽检按模板生成样板代码好可以自动修 lint、格式化、依赖升级好但依赖版本要人工确认自动确认重构跨文件老接口一般半自动先侦察再改涉及产品判断的改动差必须人工安全敏感逻辑不可接受禁止使用为什么批量重命名和样板代码这类任务效果好因为它们本质上是确定性转换规则清晰、验收标准客观。为什么产品判断类任务差因为产品逻辑需要的是“为什么这么设计”的背景理解而 t3code 能看到的是代码形态不是决策过程。多出来的“历史包袱”它没法替你判断。这张表的意义不在于清单本身而在于让团队在使用前就对齐预期。预期对齐之后AI 工具就不会被神化也不会被一票否决。4. 踩坑记录t3code 翻车的四种典型场景4.1 第三方依赖幻觉一本正经地建议不存在的包第一次翻车在一个日志改造任务上。我让 t3code 把项目里散落的logging.info统一到一个日志工具类。它改得很快但改完之后的代码里出现了一个我从来没见过的包我查了一下那个包根本不存在于 PyPI。它不仅在 import 里写上了还写了对应的调用代码看起来完全自洽。这是因为模型在训练数据里见过类似的工具库命名于是“合理地”编造了一个。这类问题的危险在于它埋在成百上千行 diff 里不会自己报错。我后来养成了一个习惯凡是用它引入的新依赖必须单独列出来人工核对。还让 t3code 自己在任务描述里加一条约束“不要引入任何新的第三方依赖如果确有必要请在结果里单列一个依赖变更清单。” 这比事后翻 diff 高效得多。4.2 过度删除“没用到”和“真的没用到”是两回事另一个让我印象深刻的翻车是它主动删掉了一个“看似没用”的函数。那次任务是清理一个模块的未使用代码t3code 扫描引用关系后发现某个内部函数的调用方都被替换成新实现了于是把这个函数标记为 dead code 删除了。但它不知道的是这个函数是留给外部系统回调用的接口契约还在只是项目内部不再有人调用。我直到联调时才发现问题。修复的过程不难但带来的教训很深t3code 的判断基于它能看到的代码而系统边界往往存在于它看不到的外部。从那以后凡是涉及删除的任务我都会明确写一条“删除前先列出清单我确认后再删”。它照做之后我每次都能看到完整的删除预案再也不会出现“被删了什么都不知道”的情况。4.3 测试通过不等于需求完成还有一次它给了我一个非常漂亮的测试报告新代码覆盖率从 40% 提到 78%全部用例通过。我一度很开心但后来发现它绕过了最关键的异常分支那个分支里调用了外部订单服务的接口它通过 mock 把整个服务层全部替换掉了断言只验证了 mock 被调用没验证 mock 被调用时的参数是否正确。测试通过但业务行为完全没有被保护。这个案例告诉我一个通用结论AI 生成的测试通过只能说明“它自己定义的世界里一切正常”不代表“真实世界里的行为符合预期”。所以我给测试类任务的验收清单多加了一条“打断点看关键路径的真实取值”人为把真实函数拉进测试路径验证它确实在用真实逻辑跑。4.4 权限过低时它反复绕圈最后一种翻车不是代码问题是行为问题。在某个子项目里我把权限配得过严允许目录只剩一个src/tmp/结果它面对一个本来 10 分钟能完成的任务绕了二十多分钟找不到可以落笔的文件就开始不停读文件、猜测、自我怀疑最后给出一个“我无法完成任务”的长篇解释。整个过程消耗了大量 token产出为零。这次之后我学到的经验是给 AI 的权限既不能太大也不能太小。太小会让它陷入“探索死循环”看起来在干活实际上在原地打转。合理的做法是给一个“最小但完整”的工作区——它要完成某个任务需要的相关目录都要可写但绝不能碰的区域必须锁死。这个尺度要根据任务类型动态调整而不是一刀切。5. 我给团队定下的 t3code 落地规范5.1 任务分级哪些可以自动哪些必须人来写经过几次踩坑我总结了一套任务分级现在团队里新需求进来第一件事就是给需求定级全自动档批量重命名、补注释、格式化、按模板生成。这些任务验收客观、风险低t3code 做完后只要 CI 通过就能合入。半自动档补测试、小范围重构、依赖升级。这些任务需要 t3code 先出方案我 review 方案后再让它执行。人工专享档涉及支付、权限、数据删除、对外接口契约的改动。这些任务 t3code 可以参与代码解读和方案讨论但不能直接改代码。这个分级本质上是在回答一个问题我们愿意为 AI 的失误付出多大的修复成本。修复成本越低的任务越可以放手修复成本越高的任务越要早做拦截。5.2 产出校验接入 CI 之前先过三关任何 t3code 的产出在进入正式 CI 之前都要过我自己定义的三关第一关diff 范围关。打开变更统计看它改了哪些文件是否在允许目录内有没有不该出现的大段删除。这一关 30 秒就能完成却能把绝大多数事故拦在外面。第二关新依赖关。把新增的 import 和依赖声明扫一遍逐个确认来源和版本。这关是专门针对“依赖幻觉”设计的。第三关关键路径抽查关。随机挑两到三个任务描述里提到的核心场景人工走读一遍代码路径确认逻辑确实按照预期在走而不是“输出看起来合理”。我后来把这套流程做成了一段脚本用 diff 的元数据做硬校验人工只负责抽查。这套组合拳下来t3code 的产出质量稳定了不少团队对它的信任度也上来了。信任不是靠感觉是靠可重复的校验流程。5.3 失误记录与提示词复盘最后是一点长期经验。每次 t3code 翻车我都会把当时的任务描述、它的错误输出、以及正确的做法整理成一则“失误样本”放进项目里一个专门的目录。这有几个实际用处下次再写类似任务时我会把过去的失误直接写进约束里比如“注意外部回调函数不可删”“不要引入新依赖”。失误样本积累了十几条之后能明显看出 t3code 的失误模式是有限的集中在那几类。知道了底牌之后使用它的时候心里非常踏实。这些样本还可以作为后续接入其他 AI 编码工具的验收测试集。谁能在这些场景下不犯同样的错谁就更有资格接管你的代码库。做这件事不需要花很多时间每次翻车花五分钟记录一下累积起来就是一笔只属于你自己的“AI 使用手册”。我现在的状态是t3code 进了日常工作流但没有被当成“自动驾驶”。它帮我处理了大量脏活累活也帮我更快地摸清了老仓库里那些没人愿意碰的角落同时我也付出了更严格的审查流程和时间成本。这两周体验下来最深刻的感受是AI 编码代理真正的门槛不在工具本身而在使用者在多大程度上愿意为它的输出负责。把它当成一个执行力很强但缺乏判断力的同事各取所长才是比较健康的位置。