Agentic Coding 是最近 AI 编程领域讨论热度很高的关键词。它的核心含义是编程助手不再只做单次自动补全而是能够根据任务描述规划步骤、修改多个文件、执行命令并反馈结果。吴恩达在相关讨论中提出了一个值得注意的判断Agentic Coding 时代基本功更重要。乍一听有点反直觉工具越来越聪明还需要人更辛苦吗真正上手就会发现AI 生成的代码越容易判断这些代码是否正确的难度反而越高。开发者的基本功决定了他是在用工具提升效率还是在帮工具修 bug。下面从工程实践角度拆解这个概念并给出训练基本功的方法、协作流程、环境配置和排错清单。1. 先理解 Agentic Coding 把编程任务变成了什么1.1 从自动补全到多步任务代理早期 AI 编程工具的核心是自动补全你把光标停在某一行模型预测后面的代码。这种模式对程序员的意图依赖很强生成的代码通常只是局部片段控制权始终在人手里。Agentic Coding 把这件事往前推了一步。这类工具会读取整个仓库搜索相关文件生成跨文件的改动执行测试命令然后根据运行结果继续修正。常见形态包括 GitHub Copilot 的 agent 模式、Cursor 的 Agent 功能、Claude Code以及 OpenAI Codex 等工具。它们的工作流程通常是理解任务描述、检索代码、生成补丁、运行验证、根据失败信息迭代。这个流程本质上把开发者从“手写每一行代码”变成了“定义目标、审查结果、处理失败”。于是人的角色发生了变化不再是编码器而是指挥官、审查员和故障处理员。1.2 Agentic 工具的工作流程与失败模式要理解基本功为什么重要先要看 Agentic 工具常见的工作过程。一次典型会话大致包括用户描述一个任务例如“修复用户登录后跳转错误的问题”。工具在仓库中查找与登录、跳转相关的文件。模型生成一个或多个候选改动。工具执行测试或语法检查。如果失败工具读取报错并尝试下一版。最终输出一个 diff等待用户确认。这个流程看起来自动化程度很高但实际使用中很容易出现几种失败模式失败现象常见原因结果需求理解偏了用户任务描述太模糊实现了一个错误功能改动范围过大没有限定修改文件无关代码被改乱反复尝试仍然报错模型看不到完整上下文陷入无效循环使用了不存在的 API模型记住了虚构代码运行期直接报错破坏了现有功能没有跑全量测试改一处坏一处这些失败模式都有一个共同点需要由人来识别、判断和纠正。如果你看不出需求理解偏了看不出 API 不存在看不出测试没有覆盖工具就会把错误自动放大。1.3 编程基本功在这些环节中的角色基本功不是指“背下 API 的能力”而是判断、拆解、验证和修复的能力。在和 Agentic Coding 协作时这些能力分别作用于关键环节需求拆解能力决定你能不能把模糊需求变成一个工具可以执行的任务。代码阅读能力决定你能不能看懂现有代码从而判断工具改动是否合理。调试能力决定工具失败后你能不能快速定位真正原因。测试设计能力决定你能不能写出一组用例让工具知道“什么才算做对了”。系统设计常识决定你能不能判断一次改动的影响边界。工具越自主使用者越需要能力兜底。没有基本功的人只会不断把同一个错误丢回给模型而有基本功的人可以给模型提供有效约束和准确反馈。这就是“基本功更重要”在工程层面的含义。2. 基本功不是背 API而是判断、拆解和验证2.1 需求拆解把模糊描述变成可验证子任务给 Agent 一个“用户登录后显示欢迎信息”的需求它可能生成很多种实现。问题在于这句话没有定义登录状态存在哪里欢迎信息从哪个接口获取用户名不存在时显示什么接口异常时怎么处理是否需要区分首次登录如果把这些细节都交给模型猜测结果就是碰运气。正确做法是先把需求拆成可验证子任务。需求内容可验证条件用户登录后显示欢迎信息登录接口返回 200 后页面出现“欢迎张三”用户名不存在接口返回 404页面显示“用户不存在”并保留输入接口超时页面显示“加载中”并在 3 秒后显示“请稍后重试”未登录访问欢迎页跳转到登录页并携带来源地址拆完之后最终交给 AI 的任务描述应该是一个任务清单而不是一句话。这个拆解过程本身就是基本功。它能减少 Agent 的自由发挥空间让输出更可控。2.2 代码阅读与审查快速看懂现有代码和调用链Agentic 工具最擅长生成“看起来正确”的代码但它对仓库历史、业务规则和隐藏约束的理解很有限。因此审查 AI 生成的 diff 成为高频工作。审查时要重点看几类问题是否引入了多余的依赖。是否绕过了原有的参数校验。是否复制了一段已有逻辑而不是复用函数。是否修改了与任务无关的文件。是否在错误层捕获异常导致错误被吞掉。阅读代码的常用顺序是先看函数签名和类型定义再看测试用例最后看实现细节。这样能快速判断这个函数对被调方暴露了哪些约定。如果 AI 改动了一个被多处调用的函数你需要用git diff看全部变化再用git grep找所有调用点。2.3 调试与日志分析从报错定位原因AI 生成代码后第一道关卡就是编译或运行。这时你会频繁遇到堆栈信息。很多人直接把报错复制给 AI让它修正这是可行的但不是最有效的方式。更高效的思路是“先缩小范围再定点修复”。比如看到这样一段 Python 报错Traceback (most recent call last): File app/services/order.py, line 42, in create_order total calculate_total(items, discount_code) File app/services/pricing.py, line 18, in calculate_total return sum(item.price * item.quantity for item in items) AttributeError: dict object has no attribute price不要急着让 AI 重写整个函数。先确认items里传入的是字典而不是对象再找数据来源。使用python -u或pytest --tbshort可以缩短日志使用print或日志输出关键变量类型可以让问题更早暴露。关键在于AI 只能根据你提供的上下文推理真正能确认“代码为什么走到这一步”的人是你。2.4 测试设计写出让 AI 按约束实现的测试测试是约束 Agent 行为的好工具。让 AI 先实现代码再补测试很容易出现“测试配合实现”的情况。反过来先写测试再让 AI 实现能明确验收标准。例如要实现一个折扣计算函数可以先写测试文件# tests/test_discount.py from app.pricing import calculate_discount def test_no_discount_when_amount_below_threshold(): assert calculate_discount(80, None) 80 def test_percent_discount(): assert calculate_discount(200, SAVE10) 180 def test_fixed_discount(): assert calculate_discount(500, OFF50) 450 def test_discount_does_not_make_total_negative(): assert calculate_discount(20, OFF50) 0然后把测试文件给 Agent要求它实现对应的calculate_discount。这样工具会尽量让代码通过测试而不是自由发挥。更重要的是这些测试会成为后续回归的防线避免它改一个地方弄坏另一个功能。测试设计能力因此从“质量保障手段”变成了“与 AI 协作的接口协议”。2.5 系统设计常识理解模块边界、数据流和异常传递基本功还包括对系统整体结构的理解。一个模块改动可能影响接口层、服务层、数据层甚至消息队列和定时任务。需要能回答以下问题数据从哪来经谁处理写到哪去。异常在哪一层被捕获哪些异常需要抛出。配置项在哪加载修改后是否需要重启。是否涉及并发、缓存、事务和幂等。设计问题不理解时可能发生的错误模块边界不清AI 把逻辑写在 Web 层SQL 查询直接散落在接口中调用链不清修改了公共函数却没有检查所有调用方事务边界不清一段代码中途失败产生脏数据缓存逻辑不清更新数据库后没有清理缓存读到旧数据异常处理不清捕获Exception后吞掉错误问题无法排查这些知识通常来自实际项目积累但也可以通过阅读优秀的开源代码、画系统流程和复盘线上故障来刻意训练。3. 和 Agent 协作时的最小闭环实践3.1 先写验收条件再交给工具和 Agent 协作的第一步不是打开对话框而是先把任务写清楚。推荐在项目根目录或当前 feature 分支里建立一个临时任务文件例如TASK.md内容包括# 任务修复订单列表分页为空的问题 ## 背景 管理后台订单列表调用 /api/orders 接口当 page2 时返回空数组。 期望行为第二页返回真实数据不返回空数组。 ## 约束 - 只修改后端相关文件不修改前端。 - 不得改变接口返回结构。 - 保持现有分页参数不变page, page_size。 - 需要补充至少一个测试用例。 ## 验证方式 - 运行 pytest tests/test_orders.py -x。 - 运行 python app/manage.py shell -c ... 模拟请求。把TASK.md的内容粘贴给 Agent比一句“修复分页问题”有效得多。写验收条件的过程就是强制自己想清楚预期结果的过程。3.2 用测试用例约束生成结果前面提到的test_discount.py已经展示了“测试先行”思路。在项目里我们可以按以下小循环工作先写一个失败的测试代表“当前行为不符合预期”。把测试和任务描述交给 Agent。Agent 生成实现代码并自行运行测试。测试通过后对实现做代码审查。有异议时通过补充测试/修改 prompt 让 Agent 调整。这个循环对应测试驱动开发TDD的 Red-Green-Refactor 思想。区别在于Red 和 Refactor 由人完成Green 可以让 AI 辅助完成。这样做的好处是验收标准被写进可执行代码Agent 不能靠口头解释过关。3.3 审查并重构 AI 生成的代码AI 生成的代码即使能通过测试也不一定适合长期维护。审查时要关注可读性、一致性和设计合理性。下面是一个小型审查清单变量名是否表达真实含义而不是data1、result2。是否有重复逻辑可以抽成公共函数。是否硬编码了路径、端口、密钥等配置。是否忽略了空值、超时和并发场景。是否在纯函数中做了 IO 操作。是否修改了与任务无关的依赖文件。对生成代码的重构应该继续交给 AI 吗可以但需要更明确的指令。例如“把这段重复逻辑提取为format_user_name函数并保持测试通过”。不要用“优化一下”这种模糊指令否则可能得到不可预期的新改动。3.4 用版本控制保留可回退边界Agent 连续修改代码时很容易出现越改越乱的情况。为了避免不可控应该让每次尝试都处于可回退状态。推荐的做法# 在一个新的 feature 分支工作 git checkout -b agent-fix-order-pagination # 确保工作区干净如果有未提交改动先提交 git status git add . git commit -m chore: save state before agent changes # 让 Agent 修改代码运行测试 # 如果不满意回到初始状态 git reset --hard HEAD这里要特别注意git reset --hard HEAD会丢弃未提交的改动。如果 Agent 的改动有价值但仍有问题应该先把当前改动提交到一个临时分支再继续调试而不是直接丢弃。版本控制不只是防手误也是给 Agent 的试错兜底。注意不要把密钥、敏感配置和大型二进制文件放进仓库。Agent 会读取仓库内容仓库里的敏感信息可能被写入生成代码或日志。4. 环境准备搭建一个适合 Agent 辅助的本地工程4.1 仓库结构清晰Agent 才能定位文件Agentic 工具依赖代码检索定位文件。仓库结构越清晰模型越容易找到正确的模块。一个常见的 Python 项目结构如下project/ ├── app/ │ ├── __init__.py │ ├── main.py │ ├── models.py │ ├── repositories/ │ ├── services/ │ └── api/ ├── tests/ │ ├── test_discount.py │ └── test_orders.py ├── pyproject.toml ├── README.md └── .env.example实际项目可能有自己的约定但最核心的一点是目录名和文件名能表达业务意图。不要把逻辑全部堆在utils.py或common.py否则 Agent 很难判断该改哪个文件。4.2 静态检查和格式化配置Agent 生成的代码很可能在风格上不一致或者包含类型问题。建议在项目里配置静态检查工具并把检查命令作为验证步骤。以 Python 为例使用ruff做 lint 和格式检查使用mypy做类型检查。pyproject.toml可以配置如下[tool.ruff] line-length 100 target-version py311 [tool.ruff.lint] select [E, F, W, I, N, UP] ignore [E501]代码提交前运行ruff check . ruff format --check . mypy app把这三个命令写进 Agent 的验证步骤就能减少生成代码的风格混乱。更重要的是静态检查失败时Agent 能看到明确错误并据此修正。4.3 运行脚本和测试命令要让 Agent 自主验证需要统一入口。常见的做法是写一个Makefile.PHONY: lint test run lint: ruff check . ruff format --check . mypy app test: pytest -q run: python -m app.main在任务描述中直接写“运行make lint和make test确保通过”比让 Agent 猜测命令更可靠。命令记录在项目文档里不仅对 Agent 有用对新人也友好。4.4 配置 AI 工具的规则文件很多 Agentic 工具支持读取项目级规则文件。常见的文件包括.cursorrules、AGENTS.md、CLAUDE.md等。具体支持情况因工具而异但可以统一在AGENTS.md中写清楚# 项目约定 ## 技术栈 - Python 3.11 FastAPI - PostgreSQL 15 - SQLAlchemy 2.x ## 常用命令 - 测试pytest -q - 启动uvicorn app.main:app --reload - 静态检查make lint ## 编码规范 - 不在 API 层直接写 SQL。 - 错误信息统一使用中文提示不抛出原始异常。 - 修改模型字段后必须提供迁移脚本。 - 新功能必须配套测试。 ## 提交前检查 1. 运行 make lint。 2. 运行 make test。 3. 检查 git status 是否包含无关文件。规则文件的价值在于把团队约定变成 Agent 的上下文。如果没有这些规则工具只会按照通用代码风格输出大概率不符合项目要求。规则文件不是一次写完就结束而是在每次失败后继续补充。5. 常见问题排查当 AI 生成的代码不工作时5.1 现象代码报错但修改多次仍然无效典型场景Agent 看着异常信息改了四五轮结果还是同样的错误。这可能不是模型不够聪明而是它没有拿到关键上下文。优先检查报错堆栈是否完整是否缺少文件行号。是否修改了正确的文件还是模型在另一个副本上做修改。依赖是否安装虚拟环境是否激活。报错是否来自缓存旧代码。命令参考# 查看当前环境 which python python --version # 查看文件修改情况 git status git diff -- app/ # 运行单个测试并显示详细输出 pytest tests/test_orders.py -x --tbshort如果代码确认修改了报错还是旧路径考虑重启开发服务器、清除__pycache__或重新安装依赖。5.2 现象生成了不存在的 API 或依赖AI 是概率模型会生成“看起来存在”的方法或包。常见报错是AttributeError、ModuleNotFoundError或ImportError。例如模型生成了from fastapi import middleware但实际包并不直接暴露这个模块。检查方式python -c import fastapi; print(dir(fastapi)) python -c from fastapi import middleware确认 API 是否存在后再决定是重新生成还是修正 import。更有效的方法是让 Agent 在生成代码前先查官方文档或者把相关文档片段直接作为上下文提供。不要把文档中的示例当作唯一真相版本不同 API 可能已经从标准库移到了第三方库。5.3 现象改了一处其他模块全挂了这是 Agentic 工具最常见的问题之一。它可能为了满足当前测试修改了一个公共函数导致其他调用方行为变化。处理步骤先看git diff --stat确认改动文件数量。查看公共函数的所有调用方。运行全量测试而不是只看当前模块。如果是接口行为变化检查接口返回结构是否被前端依赖。常用命令git diff --stat git grep calculate_total -- app tests pytest -q如果 Agent 改坏了公共函数建议在任务描述中明确“不允许修改公共函数只能新增函数”或“修改前先列出所有调用方”。这是约束 Agent 改动范围的有效方式。5.4 排查优先顺序表当 AI 生成代码不工作时建议按以下顺序排查顺序检查项方法常见结果1报错信息查看完整堆栈定位到根因文件2修改的文件git diff --stat改错文件或改动过大3依赖版本pip list或poetry show安装版本与文档不一致4配置内容检查环境变量和配置文件配置未加载或路径错误5权限和端口ls -l、lsof -i :端口文件不可读、端口被占用6缓存与热更新重启服务、清理缓存代码未生效这个顺序的原则是从“确定的事实”开始逐步走向“不确定的假设”。不要一上来就让 AI 重写整个模块。注意AI 的迭代修复很容易陷入“修一个 bug引出一个新 bug”。建议每轮修改后都运行一次全量测试而不是只运行失败的那一个用例。6. 基本功训练清单与持续实践路径6.1 每天 30 分钟练习组合基本功不能用“看视频”代替需要持续练习。适合每天投入的时间组合10 分钟读一段开源代码回答“这个模块对外提供什么能力”。10 分钟为一个已有函数写一组边界测试。10 分钟让 AI 生成一段实现然后手动重构并解释每个改动。这三个动作分别训练代码阅读、测试设计和审查能力。如果时间不够至少保留“写测试 看 diff”两项。6.2 项目式训练做一个小到能快速完成的项目与 Agent 协作时最容易忽略的是自己对业务和数据的理解。要训练这一点可以做一个小型 CLI 工具项目例如笔记本命令行管理工具。Markdown 文件批量重命名工具。局域网内文件同步脚本。日志文件统计工具。项目不追求使用最新框架重点是把需求拆解、数据结构设计、测试和异常处理完整走一遍。建议第一个版本尽量少用 Agent第二个版本再用 Agent 辅助对比哪种方式能让你更快发现问题。6.3 代码评审清单无论是否有 AI 参与提交代码前都可以按下面的清单自查功能实现是否满足验收条件。是否附带测试测试是否覆盖正常和异常分支。是否有重复逻辑可以抽取。是否处理了空值、超时、并发等边界。是否修改了与任务无关的文件。配置、密钥是否被硬编码。日志是否足够定位问题。是否运行了静态检查和全量测试。这些条目不复杂但能显著减少低级错误。可以把这份清单放在.github/pull_request_template.md里形成团队约定。6.4 学习环境与生产环境的差异用 Agentic 工具练习时学习环境和生产环境的目标不同做法也要区分。维度学习环境生产环境目标学会思路和验证方法稳定、可维护、可回滚AI 使用频率可以多轮尝试需要限制改动范围测试要求基本功能通过全量测试、回归验证安全检查不涉及敏感数据密钥、权限、审计必须严格失败处理直接改代码先看日志、监控、告警在真实项目中不要因为 Agent 能快速写代码就跳过代码评审、安全审查和性能压测。AI 可以生成“能跑的代码”但不能代替生产环境必须的质量流程。7. 回到基本功工具越强判断力越值钱吴恩达的观点放在今天的工程环境里越来越像一句实用建议而不是口号。Agentic Coding 确实让写代码的“手部工作”大幅减少但也把更多责任压到“脑部工作”上定义任务、约束行为、审查结果、处理异常。这些都依赖基本功。下一步可以从一个小练习开始找一个小项目写清楚验收条件补充测试用例让 Agent 实现功能然后认真审查 diff。经历一次完整闭环后你就会明白基本功并不是和 AI 工具竞争的东西而是使用工具的杠杆。没有基本功的人只会看到工具的随机性有基本功的人能让工具的随机性变成自己的效率。