真实工程里的 AI Coding难点从来不是让 AI 写出能运行的代码而是让 AI 完成一件具体的工作。很多团队已经接入了 AI 编程工具也用 Agent 生成过功能模块但结果往往是小任务能用大任务失控demo 能跑通合入主干就出问题。这个差距背后缺的不是工具是一套把 AI Coding 转成“干活技能”的方法。所谓 Do Work Skill就是围绕真实工作任务设计的提示、执行、评审、反馈闭环先定义清楚任务再观察项目约束接着安排 AI 的工作流程控制每一步输出评审结果最后把经验沉淀下来。下面按这套思路从工具链搭建讲起覆盖任务拆解、提示词设计、代码验证和故障排查目标是让 AI Coding 从“玩具”变成“生产力工具”。1. 先看清 AI Coding 在真实工程里到底解决什么问题1.1 从“补全代码”到“完成工作任务”AI Coding 不是一个新概念但它在工程里的形态已经发生了明显变化。最早期的形态是编辑器里的代码补全模型根据当前光标位置预测下一段代码之后演变为对话框里的代码生成工程师把需求描述成自然语言模型返回一段代码现在更常见的形态是 AI Coding Agent它不仅能生成代码还能读取项目文件、运行命令、执行测试、根据报错自动修正。这三层形态对应的工程价值完全不同。形态交互方式适合场景对工程师的要求代码补全光标位置触发写样板代码、补参数、写重复逻辑能判断补全结果是否正确代码生成对话描述需求生成函数、接口实现、单元测试能把需求描述清楚能评审代码Agent 自主执行下发任务后自动完成跨文件修改、重构、修复测试、实现小功能能把任务拆解成可验证的步骤能控制风险真实工程师最需要的能力不是记住某个工具的快捷键而是能把一个模糊的需求转成 Agent 可以执行的任务并且能在执行过程中不断给出反馈。这个能力就是 Do Work Skill 的起点。1.2 AI Coding Agent 与普通补全工具的差异AI Coding Agent 和普通工具最大的差异在于它拥有“行为能力”。普通补全工具只负责输出文本Agent 可以调用外部工具读写文件、执行 shell 命令、启动测试、查看日志、修改依赖配置。这意味着 AI 的影响范围从“光标附近的代码”扩大到了“整个工作区”。这种能力带来的收益很明显比如让 Agent 自动定位测试失败原因、修改实现、再跑一遍测试整个过程不需要人工介入太多。但风险也同样明显Agent 可能修改了不该改的文件可能在执行命令时触发副作用可能因为某个隐藏约束没有理解把原本稳定的模块改出了新问题。所以使用 Agent 时需要给它设定三件事工作边界允许读写哪些目录不允许动哪些目录。验证方式每一步完成之后怎样确认结果是正确的。回退策略如果改坏了如何恢复到上个可用状态。这些不是工具自带的而是工程师在使用前需要建立的工作习惯。换句话说AI Coding 工具越强对工程师的过程控制能力要求越高。1.3 什么是 Do Work SkillDo Work Skill 可以理解为一套把 AI Coding 转化为实际交付物的方法组合。它不是某个模型或某个 IDE 插件而是围绕“完成任务”设计的工作流。为了便于记忆和使用可以按 DOWORK 框架组织字母环节要解决的问题常见失误DDefine 定义任务要做什么达到什么标准算完成需求没写清楚就开干OObserve 观察约束项目结构、技术栈、既有规范、依赖版本让 AI 自创一套风格WWorkflow 设计流程任务怎么拆先做什么后做什么一个大 Prompt 丢给 AIOOutput 控制输出代码、测试、说明文档的产出粒度让 AI 一次生成过多内容RReview 评审验证代码是否正确、是否引入风险生成完直接合入KKeep 沉淀经验把提示词、清单、坑沉淀到项目每次都从零开始这套框架的关键在于AI Coding 不是“让 AI 自己干”而是“工程师带着 AI 一起把事干完”。接下来几节会把这个框架落到具体操作上。2. 搭建一套可落地的 AI Coding 工作环境2.1 工具链选型编辑器、Agent、CLI 如何组合学习 AI Coding 时很多人会陷入一个误区拿到工具就疯狂生成代码结果发现生成速度很快但代码质量不可控。正确做法是先搭建一套可复现的工具链再用最小工程验证链路最后再逐步放大任务范围。常见组合方式有三类组合类型适合场景注意事项IDE 内置助手日常开发、写单元测试、解释代码上下文通常受限于当前文件跨文件能力弱Agent CLI 工具自动改代码、跑测试、修复问题需要配置模型 API、工作目录和权限云端 AI 编码平台前端原型、快速做 demo、生成页面对本地工程的控制力有限适合探索不适合直接交付以前端原型任务为例Vercel 这类平台提供的 AI 生成体验可以快速从描述生成界面体验非常接近“vibe coding”。但生成结果通常是一段独立页面或组件要接入真实工程仍然需要工程师把产物放入正式项目补齐路由、接口、错误处理和测试。另一些模型服务商推出的 coding plan 订阅服务则在 IDE 和 CLI 场景中把模型能力接入日常编码流程适合需要频繁修改本工程文件的开发者。选型时建议先确认三件事工具能否读取本地工程文件、能否执行命令、执行权限是否可控。不要只看模型名字或者宣传的编码速度。工具迭代很快落地前要以官方文档的当前版本为准用一个小任务实测不要盲信评测榜单。2.2 把项目上下文整理成 AI 能理解的信息很多 AI Coding 失败的原因不是模型不够聪明而是项目缺少“机器可读”的上下文。人类开发者看项目时会先看 README、目录结构、既有代码风格但 AI Agent 也一样需要这些信息。如果项目里没有一份说明文件Agent 就只能猜测。建议在项目根目录维护一份规则文件例如AGENTS.md或CLAUDE.md具体名称取决于所用工具。这份文件可以包含# 项目开发规则 ## 技术栈 - 后端Python 3.11 FastAPI - 数据库PostgreSQL 15 - 测试pytest httpx - 包管理uv ## 代码风格 - 类型注解必须完整函数参数和返回值都要标注类型 - 数据库访问统一走 repository 层禁止在路由函数里直接写 SQL - 错误码遵循 internal-xxx / validate-xxx / upstream-xxx 命名 ## 开发命令 - 安装依赖uv sync - 启动服务uv run uvicorn app.main:app --reload - 跑测试uv run pytest - 代码检查uv run ruff check . ## 注意事项 - config 目录下的配置不允许硬编码环境变量名 - migrations 脚本由 Alembic 生成不手工修改这样一份文件可以显著降低 AI 生成代码的偏移率。它让 Agent 在开始工作前先了解约束而不是靠用户一次对话反复纠正。注意规则文件要真实反映项目现状。如果项目实际情况和文件描述不一致AI 会因为“信任文件而不信任代码”而产生错误判断。2.3 用最小工程先验证工具链路正式处理大任务之前先用一个最小工程把工具链路跑通。这个验证的目的是确认四件事模型 API 是否可用、Agent 能否读写指定目录、命令能否执行、测试能否反馈结果。假设项目是一个简单的 Python 函数库可以用下面的命令初始化mkdir ai-coding-smoke-test cd ai-coding-smoke-test git init python -m venv .venv source .venv/bin/activate pip install pytest mkdir src tests然后给 Agent 一个最小任务在src下创建calculator.py实现add和divide两个函数并在tests下创建test_calculator.py最后运行测试。任务完成后需要人工确认文件是否创建在预期位置。函数签名是否符合描述。测试用例是否覆盖了正常和异常分支。pytest是否通过。这一步的检查点不是“代码能不能跑”而是“AI 能不能按工程约定工作”。如果最小链路里 AI 就乱建文件那放到大任务里只会更乱。3. 用 Do Work Skill 拆解一个真实开发任务3.1 把任务转成可执行规格很多 AI Coding 失败的第一个坑是任务描述太短。比如“帮我做一个订单导出功能”这个描述在公司内部传递都会产生歧义更不用说是给模型执行。真实工程师应该先把任务写成规格说明再交给 AI。一个可执行规格至少包含以下内容任务名称订单导出 Excel 接口 背景运营后台需要按日期范围导出订单列表文件通过 GET /api/admin/orders/export 下载 输入 - start_date必填日期字符串格式 yyyy-MM-dd - end_date必填日期字符串格式 yyyy-MM-dd - status可选订单状态默认全部 输出 - responseapplication/vnd.openxmlformats-officedocument.spreadsheetml.sheet - 文件列订单号、用户ID、商品名称、数量、金额、状态、创建时间 约束 - 时间范围不能超过 31 天 - 数据量超过 10 万行时需要异步生成后返回下载地址 - 金额字段保留两位小数 - 导出权限为 admin:order:export 验收标准 - 正常请求返回 Excel 文件 - start_date 晚于 end_date 时返回 400 错误码 ERROR_DATE_RANGE_INVALID - 无数据时返回空表头文件而不是空响应 - 导出操作记录操作日志这个规格写清楚后AI 不再需要猜测业务含义。即使它生成的第一版不完全满足要求工程师也能根据规格逐项检查快速指出差异。3.2 提示词模板角色、上下文、任务、约束、验收有了任务规格下一步是把它封装成提示词。提示词不需要花哨但要结构稳定。下面是一个可以直接调整使用的模板你现在是项目的资深后端工程师。 项目背景和技术栈见根目录 AGENTS.md请先阅读该文件再开始工作。 任务 实现订单导出 Excel 功能接口路径和字段定义如下 [粘贴任务规格] 实现要求 1. 先说明你的实现计划包括新增文件、修改文件、依赖变更。 2. 等用户确认计划后再开始写代码。 3. 代码必须符合项目现有风格注释使用中文。 4. 导出逻辑放到 service 层controller 层只处理参数校验和响应。 5. 使用库openpyxl如果新增依赖先说明理由。 自测要求 - 实现完成后运行 pytest并补充与导出相关的单元测试。 - 输出测试结果如果失败请自行修复后再次运行。 输出格式 - 列出所有修改过的文件路径。 - 对每个文件写一行变更说明。 - 最后写“验证结果”注明测试通过情况。 不要做的事 - 不要修改与本次任务无关的文件。 - 不要引入新的全局配置项。 - 不要使用 eval、exec 等危险函数。 - 不要在实现前直接输出完整代码。这段模板的重点是“先计划后实现”。真实工程师在评审 AI 的代码前应该先评审它的计划。如果计划本身就偏离方向代码写得再快也是浪费。3.3 控制一次工作会话的节奏AI Coding 会话不是越长越好。会话越长上下文越复杂模型遗忘早期要求的概率越高。推荐把一次任务拆成五个阶段每个阶段都做一次小验证阶段Agent 行为工程师检查点理解阅读规则文件、相关代码、任务规格确认 Agent 复述需求是否准确计划列出改动文件和实施顺序确认改动范围没有越界实现分文件写代码按计划顺序进行抽查关键文件看是否有夹带修改自测运行单元测试、静态检查、命令验证确认测试通过且没有引入新告警交付汇总改动文件、变更说明、验证结果做代码评审然后合入如果任务特别大比如跨多个模块重构不建议完全依赖一次 Agent 会话。正确的做法是把大任务拆成若干个小型任务每个小任务走一遍完整的五阶段流程。每完成一个小任务就把关键结论写进会话结论或者直接开启新会话。注意当一个 Agent 会话开始重复遗忘前面已经确认过的要求时不要继续在同一个会话里反复补充提示。保存中间产物开启新会话把必要上下文重新粘贴效果通常更好。4. 关键代码与配置让 AI 的产出可维护4.1 让 AI 遵守项目既有风格AI 生成的代码最容易出问题的不是逻辑而是风格不一致。模型训练数据来自大量开源项目它默认生成的是“大多数项目的样子”但不一定是你这个项目的样子。解决办法是在提示词里显式声明风格约束并在项目规则文件里给出可检查的标准。下面是几个可以放进规则文件的例子- 所有公共函数必须写 docstringdocstring 要说明参数、返回值和异常 - 接口返回结构统一为 { code: 0, message: success, data: ... }错误时 code 使用业务码 - 禁止在业务代码里 import 测试专用工具包 - SQL 关键字大写表名使用 snake_case - 枚举值使用 Enum 类定义禁止裸字符串比较风格约束必须是可检查的否则 AI 无法确认自己是否遵守。比如“代码要清晰”这属于不可检查而“函数必须有类型注解且 ruff 检查通过”就是可检查的。4.2 下发给 AI 的评审清单代码评审通常发生在 AI 完成输出之后。工程师可以把评审标准做成清单既用于人工评审也可以直接发给 AI 让它自查评审清单 1. 功能是否完整满足任务规格中的所有输入输出定义 2. 是否有边界情况未覆盖空数据、超大输入、非法参数、超时 3. 是否引入了新的依赖如果是版本是否锁定 4. 异常处理是否完整网络、文件、数据库等外部资源是否有超时和关闭逻辑 5. 日志是否记录了关键操作和错误信息日志内容是否包含足够上下文 6. 是否有性能隐患循环内查询数据库、大对象滞留在内存、未分批处理 7. 是否有安全问题SQL 注入、路径穿越、越权访问、敏感信息打印 8. 代码是否符合项目风格规范能否通过 lint 和类型检查建议在任务交付前让 AI 先用这份清单自检一遍并输出自检结论。AI 的自检可能不够严格但它能帮工程师快速定位明显问题人工评审时只需要关注 AI 容易忽略的部分。4.3 用 CI 和测试作为 AI 产出的安全网人工评审再仔细也无法代替自动化验证。AI 生成的代码必须和人类写的代码走同一套 CI 流程。下面是 GitHub Actions 的一个最小示例适用于 Python 项目name: ci on: push: branches: [main] pull_request: jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-pythonv5 with: python-version: 3.11 - name: Install dependencies run: | pip install -r requirements-dev.txt pip install -e . - name: Lint run: ruff check . - name: Type check run: mypy src - name: Test run: pytest --covsrc --cov-fail-under80这段配置的核心逻辑是AI 生成的代码同样要过 lint、类型检查、测试覆盖率和单元测试。如果一个 Agent 生成的改动无法通过这些关卡就不应该被合入。很多团队引入 AI Coding 后效率不升反降原因就是省掉了这一层保护让 AI 的产出直接进主干出了问题再花大量时间排查。5. 运行验证交付前必须检查的五个层次5.1 第一层输入输出验证AI 生成代码最基础的验证是确认给定输入时输出是否符合预期。很多工程师只验证了“正常路径”忽略了边界条件。以订单导出接口为例至少要验证这些用例输入场景预期结果日期范围内有订单返回合法 Excel 文件日期范围内无订单返回空表头文件start_date 晚于 end_date返回 400业务码 ERROR_DATE_RANGE_INVALID时间范围超过 31 天返回 400业务码 ERROR_RANGE_TOO_LARGE未登录用户请求返回 401无权限用户请求返回 403验证时可以直接写自动化测试也可以先用 curl 人工调用curl -i -H Authorization: Bearer $TOKEN \ https://api.example.com/admin/orders/export?start_date2025-06-01end_date2025-06-30重点不是看 HTTP 200而是看响应头Content-Type、响应体是否为文件流、文件名是否符合预期。5.2 第二层异常与副作用验证AI 经常忽略异常分支和外部副作用。比如文件导出功能里如果 Excel 文件生成到一半磁盘满了怎么办如果第三方接口超时怎么办这些分支需要工程师主动设计用例。推荐的做法是使用故障注入或 monkeypatch 模拟异常def test_export_when_excel_write_fails(tmp_path, monkeypatch): def fake_save(self, file_path): raise OSError(disk full) monkeypatch.setattr(Workbook, save, fake_save) with pytest.raises(OSError): service.export_orders(orders, tmp_path / orders.xlsx)同时要检查副作用日志是否记录异常、事务是否回滚、临时文件是否清理、操作是否重复执行。AI 生成的代码往往能覆盖主路径但清理临时文件和异常上下文记录很容易遗漏。5.3 第三层日志与可观测性验证AI 生成的代码里日志常见问题有两个不打印关键操作或者把敏感信息打进去。验证时要启动服务实际调用接口然后检查日志。# 启动服务 uvicorn app.main:app --port 8000 # 触发一次导出 curl -i http://localhost:8000/admin/orders/export?start_date2025-06-01end_date2025-06-10 # 查看日志 tail -f logs/app.log期望看到的信息包括请求开始、导出行数、耗时、导出成功或失败错误信息。不应出现的包括用户密码、token、身份证号、手机号。这一步要在测试环境验证不要在开发环境跳过。5.4 第四层性能与安全检查AI 生成代码时最容易出现性能问题的模式是循环内查询数据库、重复计算、大列表一次性加载到内存。安全方面则容易出现路径拼接不校验、越权判断放在前端、参数直接拼接 SQL。性能检查可以用两个方法看代码结构统计慢 SQL。以订单导出为例如果 AI 在循环里逐行查询用户信息数据量大时必然慢。正确做法是一条 SQL join 查出来再分页读取写文件。安全验证至少包括文件下载路径是否可控能否通过构造文件名读取任意文件。导出接口是否校验用户权限。生成的文件是否包含敏感列。文件名中是否包含用户可控字符是否有路径穿越风险。5.5 第五层用验证清单收口完成前面四层后用一个验证清单收口避免遗漏。这个清单可以沉淀到项目里每次 AI 交付都用同一份检查项验证方式结果功能用例pytest 测试通过通过 / 失败边界用例手动补充测试通过 / 失败异常分支monkeypatch 模拟通过 / 失败日志检查tail 日志确认通过 / 失败性能检查查询执行计划通过 / 失败安全检查代码审查 安全用例通过 / 失败风格规范ruff/mypy 通过通过 / 失败这套清单是 Do Work Skill 中 Review 环节的落地工具。每个项目可以按技术栈调整但核心原则不变AI 的产出必须经过与人类代码同等的验证。6. 常见问题排查AI Coding 生产事故的定位路径6.1 现象一AI 改动一处代码其他功能跟着挂AI 在做跨文件修改时经常只看到自己需要改的上下文看不到调用方的依赖约束。比如把某个函数的参数类型从str改成int数据库字段也跟着改但调用方没同步更新。排查路径用git diff查看改动范围确认是否涉及本任务之外的代码。用git log找到 AI 修改前最近一次通过测试的提交。运行完整测试套件定位失败用例。根据失败用例追溯调用链。git diff HEAD~1 --stat git status git checkout -- src/path/unchanged_file.py解决方案是回退无关改动然后在提示词中增加约束只允许修改与该功能相关的文件修改接口签名前先列出所有调用方。6.2 现象二AI 生成代码不符合项目规范AI 输出风格和项目不一致通常是规则文件缺失或规则不够具体。如果项目没有AGENTS.md这类文件AI 只能按照训练数据里的通用风格生成。排查路径检查项目规则文件是否存在。检查提示词里是否声明了具体规范。用 lint 工具列出具体违规项反馈给 Agent 修正而不是让 AI 自己猜测。ruff check . mypy src pytest tests/预防方法是把风格规范从“口头约定”改成“可执行检查”并且要求 AI 在交付前自跑一遍。6.3 现象三Agent 反复陷入同一个错误Agent 修改代码后测试仍然失败而且每次都是同一个原因说明它没有真正理解错误根因。常见情况是只看到报错表面却没有排查上游数据或配置。排查路径拿到完整错误堆栈而不是只看最后一行。要求 Agent 先解释报错原因再提交修复方案。检查是否重复修同一个文件但没查找同样模式的其他位置。pytest -x -q --tblong解决方案是中断当前会话。把完整错误信息和相关日志粘贴到新会话明确要求 Agent先分析根因列出可能原因再写修复代码。6.4 现象四Agent 上下文过长开始遗忘早期要求当任务很大Agent 在会话后期出现遗忘早期要求、重复提问、执行前后矛盾时通常是上下文窗口已经变得很长模型无法有效聚焦。排查路径回看 Agent 执行历史找到第一次行为偏移的节点。把已确认的规格和中间产物保存到独立文件。开启新会话在新会话中粘贴必要上下文继续从断点执行。问题现象常见原因检查方式处理建议改一处挂多处改动范围越界git diff 完整测试回退无关改动限制工作目录代码风格不一致缺少规则文件检查 AGENTS.md补充可执行规范要求自检反复同样报错未定位根因完整堆栈 根因分析中断会话重新分析越聊越跑偏上下文过长回看行为偏移节点保存产物新会话继续排查核心原则先还原现象再确认改动范围最后用测试判断根因。不要因为代码是 AI 写的就另搞一套排查流程AI 代码和人类代码的故障排查在工程层面是一致的。7. 最佳实践与扩展方向7.1 真实工程师使用 AI Coding 的十条建议这十条建议来自多个项目的实践总结可以直接作为团队协作规范每个任务先写规格说明再写提示词规格比提示词重要。在项目根目录维护规则文件并要求 AI 先读再写。一次会话只处理一个任务任务过大就拆分。永远先让 AI 给计划确认后再写代码。修改文件前要求 AI 列出将要修改的文件列表人工确认。AI 生成的代码必须走同样的 lint、测试、评审流程。关键模块不直接合入代码评审时重点检查异常和副作用。遇到方向性错误不要在同一次会话里反复纠正开启新会话。把好用的提示词模板和踩过的坑沉淀到团队文档。保持工程判断力AI 给出方案时要问“为什么”而不是直接接受。7.2 学习环境与生产环境要分开对待维度学习环境生产环境任务类型原型、demo、练习题核心业务、数据一致性、权限敏感功能数据真实度模拟数据真实数据注意脱敏权限控制无限制或宽松最小权限限制目录修改验证强度能跑起来即可完整单测、集成测试、安全扫描上下文策略一个会话跑到底阶段性保存中间产物必要时新会话评审标准看逻辑对不对看边界、性能、安全、可维护性回滚方案不需要需要版本管理、灰度发布、快速回滚学习环境里可以大胆探索各种提示词生产环境则要严格按工作流执行。7.3 下一步从个人使用到团队工作流Do Work Skill 的第一步是个人能力第二步是团队协作。个人层面可以把常用的任务规格模板、提示词模板和验证清单整理成个人笔记。团队层面可以把这些模板放在项目仓库的docs/ai-coding目录下让所有成员和后续接入的 AI Coding 工具使用同一套标准。扩展方向有三个维护团队级规则文件覆盖语言、框架、数据库、部署方式的统一约定。在 CI 中加入 AI 生成的变更检测例如通过提交信息中特定标记识别 AI 改动执行更高强度的评审策略。建立 AI Coding 反馈数据集把每次纠正 Agent 的错误、无效生成、误改文件记录下来形成团队的“反面案例库”在写提示词时直接引用。AI Coding 的能力边界一直在扩展工具更新也很快但工程方法相对稳定。无论使用哪个平台、哪个模型把任务定义清楚、约束交代清楚、验证流程建好AI 的产出才能真正进入生产系统。工程师真正的护城河不是会用某个 AI 工具而是能在 AI 生成大量代码时保持判断力知道哪些可以合入、哪些必须重写、哪些需要先补测试。建议从一个真实的小任务开始用完整的 DOWORK 流程走一遍把模板和方法沉淀下来再逐步放大任务范围这是目前最多人验证过的学习路径。 AI Coding 工程化：用 Do Work Skill 让 Agent 真正干活
真实工程里的 AI Coding难点从来不是让 AI 写出能运行的代码而是让 AI 完成一件具体的工作。很多团队已经接入了 AI 编程工具也用 Agent 生成过功能模块但结果往往是小任务能用大任务失控demo 能跑通合入主干就出问题。这个差距背后缺的不是工具是一套把 AI Coding 转成“干活技能”的方法。所谓 Do Work Skill就是围绕真实工作任务设计的提示、执行、评审、反馈闭环先定义清楚任务再观察项目约束接着安排 AI 的工作流程控制每一步输出评审结果最后把经验沉淀下来。下面按这套思路从工具链搭建讲起覆盖任务拆解、提示词设计、代码验证和故障排查目标是让 AI Coding 从“玩具”变成“生产力工具”。1. 先看清 AI Coding 在真实工程里到底解决什么问题1.1 从“补全代码”到“完成工作任务”AI Coding 不是一个新概念但它在工程里的形态已经发生了明显变化。最早期的形态是编辑器里的代码补全模型根据当前光标位置预测下一段代码之后演变为对话框里的代码生成工程师把需求描述成自然语言模型返回一段代码现在更常见的形态是 AI Coding Agent它不仅能生成代码还能读取项目文件、运行命令、执行测试、根据报错自动修正。这三层形态对应的工程价值完全不同。形态交互方式适合场景对工程师的要求代码补全光标位置触发写样板代码、补参数、写重复逻辑能判断补全结果是否正确代码生成对话描述需求生成函数、接口实现、单元测试能把需求描述清楚能评审代码Agent 自主执行下发任务后自动完成跨文件修改、重构、修复测试、实现小功能能把任务拆解成可验证的步骤能控制风险真实工程师最需要的能力不是记住某个工具的快捷键而是能把一个模糊的需求转成 Agent 可以执行的任务并且能在执行过程中不断给出反馈。这个能力就是 Do Work Skill 的起点。1.2 AI Coding Agent 与普通补全工具的差异AI Coding Agent 和普通工具最大的差异在于它拥有“行为能力”。普通补全工具只负责输出文本Agent 可以调用外部工具读写文件、执行 shell 命令、启动测试、查看日志、修改依赖配置。这意味着 AI 的影响范围从“光标附近的代码”扩大到了“整个工作区”。这种能力带来的收益很明显比如让 Agent 自动定位测试失败原因、修改实现、再跑一遍测试整个过程不需要人工介入太多。但风险也同样明显Agent 可能修改了不该改的文件可能在执行命令时触发副作用可能因为某个隐藏约束没有理解把原本稳定的模块改出了新问题。所以使用 Agent 时需要给它设定三件事工作边界允许读写哪些目录不允许动哪些目录。验证方式每一步完成之后怎样确认结果是正确的。回退策略如果改坏了如何恢复到上个可用状态。这些不是工具自带的而是工程师在使用前需要建立的工作习惯。换句话说AI Coding 工具越强对工程师的过程控制能力要求越高。1.3 什么是 Do Work SkillDo Work Skill 可以理解为一套把 AI Coding 转化为实际交付物的方法组合。它不是某个模型或某个 IDE 插件而是围绕“完成任务”设计的工作流。为了便于记忆和使用可以按 DOWORK 框架组织字母环节要解决的问题常见失误DDefine 定义任务要做什么达到什么标准算完成需求没写清楚就开干OObserve 观察约束项目结构、技术栈、既有规范、依赖版本让 AI 自创一套风格WWorkflow 设计流程任务怎么拆先做什么后做什么一个大 Prompt 丢给 AIOOutput 控制输出代码、测试、说明文档的产出粒度让 AI 一次生成过多内容RReview 评审验证代码是否正确、是否引入风险生成完直接合入KKeep 沉淀经验把提示词、清单、坑沉淀到项目每次都从零开始这套框架的关键在于AI Coding 不是“让 AI 自己干”而是“工程师带着 AI 一起把事干完”。接下来几节会把这个框架落到具体操作上。2. 搭建一套可落地的 AI Coding 工作环境2.1 工具链选型编辑器、Agent、CLI 如何组合学习 AI Coding 时很多人会陷入一个误区拿到工具就疯狂生成代码结果发现生成速度很快但代码质量不可控。正确做法是先搭建一套可复现的工具链再用最小工程验证链路最后再逐步放大任务范围。常见组合方式有三类组合类型适合场景注意事项IDE 内置助手日常开发、写单元测试、解释代码上下文通常受限于当前文件跨文件能力弱Agent CLI 工具自动改代码、跑测试、修复问题需要配置模型 API、工作目录和权限云端 AI 编码平台前端原型、快速做 demo、生成页面对本地工程的控制力有限适合探索不适合直接交付以前端原型任务为例Vercel 这类平台提供的 AI 生成体验可以快速从描述生成界面体验非常接近“vibe coding”。但生成结果通常是一段独立页面或组件要接入真实工程仍然需要工程师把产物放入正式项目补齐路由、接口、错误处理和测试。另一些模型服务商推出的 coding plan 订阅服务则在 IDE 和 CLI 场景中把模型能力接入日常编码流程适合需要频繁修改本工程文件的开发者。选型时建议先确认三件事工具能否读取本地工程文件、能否执行命令、执行权限是否可控。不要只看模型名字或者宣传的编码速度。工具迭代很快落地前要以官方文档的当前版本为准用一个小任务实测不要盲信评测榜单。2.2 把项目上下文整理成 AI 能理解的信息很多 AI Coding 失败的原因不是模型不够聪明而是项目缺少“机器可读”的上下文。人类开发者看项目时会先看 README、目录结构、既有代码风格但 AI Agent 也一样需要这些信息。如果项目里没有一份说明文件Agent 就只能猜测。建议在项目根目录维护一份规则文件例如AGENTS.md或CLAUDE.md具体名称取决于所用工具。这份文件可以包含# 项目开发规则 ## 技术栈 - 后端Python 3.11 FastAPI - 数据库PostgreSQL 15 - 测试pytest httpx - 包管理uv ## 代码风格 - 类型注解必须完整函数参数和返回值都要标注类型 - 数据库访问统一走 repository 层禁止在路由函数里直接写 SQL - 错误码遵循 internal-xxx / validate-xxx / upstream-xxx 命名 ## 开发命令 - 安装依赖uv sync - 启动服务uv run uvicorn app.main:app --reload - 跑测试uv run pytest - 代码检查uv run ruff check . ## 注意事项 - config 目录下的配置不允许硬编码环境变量名 - migrations 脚本由 Alembic 生成不手工修改这样一份文件可以显著降低 AI 生成代码的偏移率。它让 Agent 在开始工作前先了解约束而不是靠用户一次对话反复纠正。注意规则文件要真实反映项目现状。如果项目实际情况和文件描述不一致AI 会因为“信任文件而不信任代码”而产生错误判断。2.3 用最小工程先验证工具链路正式处理大任务之前先用一个最小工程把工具链路跑通。这个验证的目的是确认四件事模型 API 是否可用、Agent 能否读写指定目录、命令能否执行、测试能否反馈结果。假设项目是一个简单的 Python 函数库可以用下面的命令初始化mkdir ai-coding-smoke-test cd ai-coding-smoke-test git init python -m venv .venv source .venv/bin/activate pip install pytest mkdir src tests然后给 Agent 一个最小任务在src下创建calculator.py实现add和divide两个函数并在tests下创建test_calculator.py最后运行测试。任务完成后需要人工确认文件是否创建在预期位置。函数签名是否符合描述。测试用例是否覆盖了正常和异常分支。pytest是否通过。这一步的检查点不是“代码能不能跑”而是“AI 能不能按工程约定工作”。如果最小链路里 AI 就乱建文件那放到大任务里只会更乱。3. 用 Do Work Skill 拆解一个真实开发任务3.1 把任务转成可执行规格很多 AI Coding 失败的第一个坑是任务描述太短。比如“帮我做一个订单导出功能”这个描述在公司内部传递都会产生歧义更不用说是给模型执行。真实工程师应该先把任务写成规格说明再交给 AI。一个可执行规格至少包含以下内容任务名称订单导出 Excel 接口 背景运营后台需要按日期范围导出订单列表文件通过 GET /api/admin/orders/export 下载 输入 - start_date必填日期字符串格式 yyyy-MM-dd - end_date必填日期字符串格式 yyyy-MM-dd - status可选订单状态默认全部 输出 - responseapplication/vnd.openxmlformats-officedocument.spreadsheetml.sheet - 文件列订单号、用户ID、商品名称、数量、金额、状态、创建时间 约束 - 时间范围不能超过 31 天 - 数据量超过 10 万行时需要异步生成后返回下载地址 - 金额字段保留两位小数 - 导出权限为 admin:order:export 验收标准 - 正常请求返回 Excel 文件 - start_date 晚于 end_date 时返回 400 错误码 ERROR_DATE_RANGE_INVALID - 无数据时返回空表头文件而不是空响应 - 导出操作记录操作日志这个规格写清楚后AI 不再需要猜测业务含义。即使它生成的第一版不完全满足要求工程师也能根据规格逐项检查快速指出差异。3.2 提示词模板角色、上下文、任务、约束、验收有了任务规格下一步是把它封装成提示词。提示词不需要花哨但要结构稳定。下面是一个可以直接调整使用的模板你现在是项目的资深后端工程师。 项目背景和技术栈见根目录 AGENTS.md请先阅读该文件再开始工作。 任务 实现订单导出 Excel 功能接口路径和字段定义如下 [粘贴任务规格] 实现要求 1. 先说明你的实现计划包括新增文件、修改文件、依赖变更。 2. 等用户确认计划后再开始写代码。 3. 代码必须符合项目现有风格注释使用中文。 4. 导出逻辑放到 service 层controller 层只处理参数校验和响应。 5. 使用库openpyxl如果新增依赖先说明理由。 自测要求 - 实现完成后运行 pytest并补充与导出相关的单元测试。 - 输出测试结果如果失败请自行修复后再次运行。 输出格式 - 列出所有修改过的文件路径。 - 对每个文件写一行变更说明。 - 最后写“验证结果”注明测试通过情况。 不要做的事 - 不要修改与本次任务无关的文件。 - 不要引入新的全局配置项。 - 不要使用 eval、exec 等危险函数。 - 不要在实现前直接输出完整代码。这段模板的重点是“先计划后实现”。真实工程师在评审 AI 的代码前应该先评审它的计划。如果计划本身就偏离方向代码写得再快也是浪费。3.3 控制一次工作会话的节奏AI Coding 会话不是越长越好。会话越长上下文越复杂模型遗忘早期要求的概率越高。推荐把一次任务拆成五个阶段每个阶段都做一次小验证阶段Agent 行为工程师检查点理解阅读规则文件、相关代码、任务规格确认 Agent 复述需求是否准确计划列出改动文件和实施顺序确认改动范围没有越界实现分文件写代码按计划顺序进行抽查关键文件看是否有夹带修改自测运行单元测试、静态检查、命令验证确认测试通过且没有引入新告警交付汇总改动文件、变更说明、验证结果做代码评审然后合入如果任务特别大比如跨多个模块重构不建议完全依赖一次 Agent 会话。正确的做法是把大任务拆成若干个小型任务每个小任务走一遍完整的五阶段流程。每完成一个小任务就把关键结论写进会话结论或者直接开启新会话。注意当一个 Agent 会话开始重复遗忘前面已经确认过的要求时不要继续在同一个会话里反复补充提示。保存中间产物开启新会话把必要上下文重新粘贴效果通常更好。4. 关键代码与配置让 AI 的产出可维护4.1 让 AI 遵守项目既有风格AI 生成的代码最容易出问题的不是逻辑而是风格不一致。模型训练数据来自大量开源项目它默认生成的是“大多数项目的样子”但不一定是你这个项目的样子。解决办法是在提示词里显式声明风格约束并在项目规则文件里给出可检查的标准。下面是几个可以放进规则文件的例子- 所有公共函数必须写 docstringdocstring 要说明参数、返回值和异常 - 接口返回结构统一为 { code: 0, message: success, data: ... }错误时 code 使用业务码 - 禁止在业务代码里 import 测试专用工具包 - SQL 关键字大写表名使用 snake_case - 枚举值使用 Enum 类定义禁止裸字符串比较风格约束必须是可检查的否则 AI 无法确认自己是否遵守。比如“代码要清晰”这属于不可检查而“函数必须有类型注解且 ruff 检查通过”就是可检查的。4.2 下发给 AI 的评审清单代码评审通常发生在 AI 完成输出之后。工程师可以把评审标准做成清单既用于人工评审也可以直接发给 AI 让它自查评审清单 1. 功能是否完整满足任务规格中的所有输入输出定义 2. 是否有边界情况未覆盖空数据、超大输入、非法参数、超时 3. 是否引入了新的依赖如果是版本是否锁定 4. 异常处理是否完整网络、文件、数据库等外部资源是否有超时和关闭逻辑 5. 日志是否记录了关键操作和错误信息日志内容是否包含足够上下文 6. 是否有性能隐患循环内查询数据库、大对象滞留在内存、未分批处理 7. 是否有安全问题SQL 注入、路径穿越、越权访问、敏感信息打印 8. 代码是否符合项目风格规范能否通过 lint 和类型检查建议在任务交付前让 AI 先用这份清单自检一遍并输出自检结论。AI 的自检可能不够严格但它能帮工程师快速定位明显问题人工评审时只需要关注 AI 容易忽略的部分。4.3 用 CI 和测试作为 AI 产出的安全网人工评审再仔细也无法代替自动化验证。AI 生成的代码必须和人类写的代码走同一套 CI 流程。下面是 GitHub Actions 的一个最小示例适用于 Python 项目name: ci on: push: branches: [main] pull_request: jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - uses: actions/setup-pythonv5 with: python-version: 3.11 - name: Install dependencies run: | pip install -r requirements-dev.txt pip install -e . - name: Lint run: ruff check . - name: Type check run: mypy src - name: Test run: pytest --covsrc --cov-fail-under80这段配置的核心逻辑是AI 生成的代码同样要过 lint、类型检查、测试覆盖率和单元测试。如果一个 Agent 生成的改动无法通过这些关卡就不应该被合入。很多团队引入 AI Coding 后效率不升反降原因就是省掉了这一层保护让 AI 的产出直接进主干出了问题再花大量时间排查。5. 运行验证交付前必须检查的五个层次5.1 第一层输入输出验证AI 生成代码最基础的验证是确认给定输入时输出是否符合预期。很多工程师只验证了“正常路径”忽略了边界条件。以订单导出接口为例至少要验证这些用例输入场景预期结果日期范围内有订单返回合法 Excel 文件日期范围内无订单返回空表头文件start_date 晚于 end_date返回 400业务码 ERROR_DATE_RANGE_INVALID时间范围超过 31 天返回 400业务码 ERROR_RANGE_TOO_LARGE未登录用户请求返回 401无权限用户请求返回 403验证时可以直接写自动化测试也可以先用 curl 人工调用curl -i -H Authorization: Bearer $TOKEN \ https://api.example.com/admin/orders/export?start_date2025-06-01end_date2025-06-30重点不是看 HTTP 200而是看响应头Content-Type、响应体是否为文件流、文件名是否符合预期。5.2 第二层异常与副作用验证AI 经常忽略异常分支和外部副作用。比如文件导出功能里如果 Excel 文件生成到一半磁盘满了怎么办如果第三方接口超时怎么办这些分支需要工程师主动设计用例。推荐的做法是使用故障注入或 monkeypatch 模拟异常def test_export_when_excel_write_fails(tmp_path, monkeypatch): def fake_save(self, file_path): raise OSError(disk full) monkeypatch.setattr(Workbook, save, fake_save) with pytest.raises(OSError): service.export_orders(orders, tmp_path / orders.xlsx)同时要检查副作用日志是否记录异常、事务是否回滚、临时文件是否清理、操作是否重复执行。AI 生成的代码往往能覆盖主路径但清理临时文件和异常上下文记录很容易遗漏。5.3 第三层日志与可观测性验证AI 生成的代码里日志常见问题有两个不打印关键操作或者把敏感信息打进去。验证时要启动服务实际调用接口然后检查日志。# 启动服务 uvicorn app.main:app --port 8000 # 触发一次导出 curl -i http://localhost:8000/admin/orders/export?start_date2025-06-01end_date2025-06-10 # 查看日志 tail -f logs/app.log期望看到的信息包括请求开始、导出行数、耗时、导出成功或失败错误信息。不应出现的包括用户密码、token、身份证号、手机号。这一步要在测试环境验证不要在开发环境跳过。5.4 第四层性能与安全检查AI 生成代码时最容易出现性能问题的模式是循环内查询数据库、重复计算、大列表一次性加载到内存。安全方面则容易出现路径拼接不校验、越权判断放在前端、参数直接拼接 SQL。性能检查可以用两个方法看代码结构统计慢 SQL。以订单导出为例如果 AI 在循环里逐行查询用户信息数据量大时必然慢。正确做法是一条 SQL join 查出来再分页读取写文件。安全验证至少包括文件下载路径是否可控能否通过构造文件名读取任意文件。导出接口是否校验用户权限。生成的文件是否包含敏感列。文件名中是否包含用户可控字符是否有路径穿越风险。5.5 第五层用验证清单收口完成前面四层后用一个验证清单收口避免遗漏。这个清单可以沉淀到项目里每次 AI 交付都用同一份检查项验证方式结果功能用例pytest 测试通过通过 / 失败边界用例手动补充测试通过 / 失败异常分支monkeypatch 模拟通过 / 失败日志检查tail 日志确认通过 / 失败性能检查查询执行计划通过 / 失败安全检查代码审查 安全用例通过 / 失败风格规范ruff/mypy 通过通过 / 失败这套清单是 Do Work Skill 中 Review 环节的落地工具。每个项目可以按技术栈调整但核心原则不变AI 的产出必须经过与人类代码同等的验证。6. 常见问题排查AI Coding 生产事故的定位路径6.1 现象一AI 改动一处代码其他功能跟着挂AI 在做跨文件修改时经常只看到自己需要改的上下文看不到调用方的依赖约束。比如把某个函数的参数类型从str改成int数据库字段也跟着改但调用方没同步更新。排查路径用git diff查看改动范围确认是否涉及本任务之外的代码。用git log找到 AI 修改前最近一次通过测试的提交。运行完整测试套件定位失败用例。根据失败用例追溯调用链。git diff HEAD~1 --stat git status git checkout -- src/path/unchanged_file.py解决方案是回退无关改动然后在提示词中增加约束只允许修改与该功能相关的文件修改接口签名前先列出所有调用方。6.2 现象二AI 生成代码不符合项目规范AI 输出风格和项目不一致通常是规则文件缺失或规则不够具体。如果项目没有AGENTS.md这类文件AI 只能按照训练数据里的通用风格生成。排查路径检查项目规则文件是否存在。检查提示词里是否声明了具体规范。用 lint 工具列出具体违规项反馈给 Agent 修正而不是让 AI 自己猜测。ruff check . mypy src pytest tests/预防方法是把风格规范从“口头约定”改成“可执行检查”并且要求 AI 在交付前自跑一遍。6.3 现象三Agent 反复陷入同一个错误Agent 修改代码后测试仍然失败而且每次都是同一个原因说明它没有真正理解错误根因。常见情况是只看到报错表面却没有排查上游数据或配置。排查路径拿到完整错误堆栈而不是只看最后一行。要求 Agent 先解释报错原因再提交修复方案。检查是否重复修同一个文件但没查找同样模式的其他位置。pytest -x -q --tblong解决方案是中断当前会话。把完整错误信息和相关日志粘贴到新会话明确要求 Agent先分析根因列出可能原因再写修复代码。6.4 现象四Agent 上下文过长开始遗忘早期要求当任务很大Agent 在会话后期出现遗忘早期要求、重复提问、执行前后矛盾时通常是上下文窗口已经变得很长模型无法有效聚焦。排查路径回看 Agent 执行历史找到第一次行为偏移的节点。把已确认的规格和中间产物保存到独立文件。开启新会话在新会话中粘贴必要上下文继续从断点执行。问题现象常见原因检查方式处理建议改一处挂多处改动范围越界git diff 完整测试回退无关改动限制工作目录代码风格不一致缺少规则文件检查 AGENTS.md补充可执行规范要求自检反复同样报错未定位根因完整堆栈 根因分析中断会话重新分析越聊越跑偏上下文过长回看行为偏移节点保存产物新会话继续排查核心原则先还原现象再确认改动范围最后用测试判断根因。不要因为代码是 AI 写的就另搞一套排查流程AI 代码和人类代码的故障排查在工程层面是一致的。7. 最佳实践与扩展方向7.1 真实工程师使用 AI Coding 的十条建议这十条建议来自多个项目的实践总结可以直接作为团队协作规范每个任务先写规格说明再写提示词规格比提示词重要。在项目根目录维护规则文件并要求 AI 先读再写。一次会话只处理一个任务任务过大就拆分。永远先让 AI 给计划确认后再写代码。修改文件前要求 AI 列出将要修改的文件列表人工确认。AI 生成的代码必须走同样的 lint、测试、评审流程。关键模块不直接合入代码评审时重点检查异常和副作用。遇到方向性错误不要在同一次会话里反复纠正开启新会话。把好用的提示词模板和踩过的坑沉淀到团队文档。保持工程判断力AI 给出方案时要问“为什么”而不是直接接受。7.2 学习环境与生产环境要分开对待维度学习环境生产环境任务类型原型、demo、练习题核心业务、数据一致性、权限敏感功能数据真实度模拟数据真实数据注意脱敏权限控制无限制或宽松最小权限限制目录修改验证强度能跑起来即可完整单测、集成测试、安全扫描上下文策略一个会话跑到底阶段性保存中间产物必要时新会话评审标准看逻辑对不对看边界、性能、安全、可维护性回滚方案不需要需要版本管理、灰度发布、快速回滚学习环境里可以大胆探索各种提示词生产环境则要严格按工作流执行。7.3 下一步从个人使用到团队工作流Do Work Skill 的第一步是个人能力第二步是团队协作。个人层面可以把常用的任务规格模板、提示词模板和验证清单整理成个人笔记。团队层面可以把这些模板放在项目仓库的docs/ai-coding目录下让所有成员和后续接入的 AI Coding 工具使用同一套标准。扩展方向有三个维护团队级规则文件覆盖语言、框架、数据库、部署方式的统一约定。在 CI 中加入 AI 生成的变更检测例如通过提交信息中特定标记识别 AI 改动执行更高强度的评审策略。建立 AI Coding 反馈数据集把每次纠正 Agent 的错误、无效生成、误改文件记录下来形成团队的“反面案例库”在写提示词时直接引用。AI Coding 的能力边界一直在扩展工具更新也很快但工程方法相对稳定。无论使用哪个平台、哪个模型把任务定义清楚、约束交代清楚、验证流程建好AI 的产出才能真正进入生产系统。工程师真正的护城河不是会用某个 AI 工具而是能在 AI 生成大量代码时保持判断力知道哪些可以合入、哪些必须重写、哪些需要先补测试。建议从一个真实的小任务开始用完整的 DOWORK 流程走一遍把模板和方法沉淀下来再逐步放大任务范围这是目前最多人验证过的学习路径。