我们开发的每一个需求，基本 80% 的时间在搞清楚该改什么，只有 20% 在写代码。这不是你能力不够，是软件的复杂度在跟你作对
接到需求：结算单状态机增加一个「部分退款」中间状态
在梳理了 SettlementService、SettlementController、SettlementStateMachine 后，改动范围很清楚——加一个枚举值，改三条状态流转路径。改动量很小，代码 review 也顺利通过。
结果上线第二天，告警来了：对账报表里部分退款的结算单被重复计入
问题出在一个没人知道的类——ReconciliationReportBuilder。它内部有一个 switch-case 遍历结算单状态来决定归入哪个科目，新增的枚举值走到了 default 分支，被当成「已结算」处理了
这个类的存在，在改代码的时候可能完全不知道。甚至不知道「我应该知道它的存在」
如果你在接手业务需求的时候也踩过类似的坑，这篇文章就是写给你的
AI 编程助手已经越来越常见。很多人会用 Claude Code、Cursor、Codex CLI 这类工具来读代码、改代码、解释架构、定位 bug。
但 AI 经常会遇到一个问题，尤其是项目比较大的时候：它并不是真的掌握了整个代码库的结构，而是在不断搜索文件、读取文件、猜测关系。
比如你问：这个请求最后是怎么走到数据库查询的？
如果没有更好的索引，AI 可能会从 route 开始搜索，打开几个 controller，再继续找 service、model、query builder。过程中它会消耗很多 token 和工具调用，而且一旦漏掉某个框架约定或隐式调用，结论就可能不完整。
而 CodeGraph 要解决的，就是这个问题。它为代码库建立一个本地的代码知识图谱，让 AI 编程助手可以直接查询代码结构，而不是每次都从零开始翻文件。
最近在读 Superpowers 里的一个 skill：subagent-driven-development。
这个 skill 很有意思。它并不是教 agent 如何写某一种代码，而是在设计一种开发流程（开发+review）：当我们已经有一个实现计划，并且计划里的任务相对独立时，主 agent 不再亲自完成所有工作，而是把每个任务派发给新的 subAgent，再通过两阶段 review 来控制质量。
它的核心思想可以用一句话概括：
每个任务派一个新的 subAgent + 两阶段审查 = 可控、高质量、低上下文污染的开发流程。
也就是说，它真正关注的不是「让更多 agent 干活」，而是「如何让多个 agent 在明确边界内协作」。
AI Coding 目前已经成为标配，但现实是有的团队效率提升 3 倍，有的团队却效果一般。问题不在 AI，而在使用方式。
很多人把 AI 当成「更聪明的程序员」：帮我实现一个XX功能， 然后会得到一段「看起来没问题」的代码
但这种方式的问题在于：
它只是基于已有上下文，生成一个「自洽的结果」，而这个结果就是：代码能运行，但是很多功能偏离预期或者边界未处理
所以关键不在于AI 能不能写代码，而在于：你有没有能力约束 AI 写出满足需求的代码
真正有效的 AI Coding，不是写 Prompt，而是一个工程模型：
1 | Context（上下文控制） |
这五个能力不是并列关系，而是一条执行链路：
1 | Task → Context → Constraint → Checkpoint → Verification |
本质是：把概率性的「生成问题」转化为「受控的执行过程」
当前，AI 的自动化「实现能力」正在迅速增强，代码生成、逻辑补全、测试构建，已经不再是主要瓶颈
目前真正决定效率上限的，正在变成：我们是否能够清晰地定义任务、边界和验收标准
当这些被完整定义后，AI 就可以自动完成实现、验证与修复，直至满足规格约束
这场变化不再是工具升级，而是工程能力结构的迁移。而规范驱动开发，正是这种迁移的实践形式
在工程讨论中，一旦提到「大模型应用开发」，立即就会出现一大堆的概念：LangChain / LangGraph、Agent Loop、Tool Calling、Memory 管理、Planning 策略、Orchestration 等等
但现实项目中，大量需求并没有复杂到需要构建运行时系统，很多场景只是希望可以封装一个能力、提供一个结构化的交互，同时可以被稳定复用
对于这类问题，更务实的路径是：不要从零构建 Agent，而是基于通用Agent 进行扩展 —— 通过编写Skills
本文将通过一个真实示例说明，如何仅通过定义一个 Skill，就实现一个完整可用的小型大模型应用
在把一件事交给 AI 之前，我们心里往往有一个隐含期待：“它应该能帮我省点事”
但实际操作中，流程通常是：先解释背景，再说明目标，中途补充"之前没写清楚但很重要"的约束，等 AI 给出结果后，开始修改、校对、推翻重来。做到一半，一个念头会自然浮现：
“这件事，我是不是自己来反而更快？”
如果你有过这种感觉，先别急着怀疑 AI，也别急着怀疑自己。更可能的问题是：我们一开始就在问一个不太对的问题
Most best practices are based on one constraint: Claude’s context window fills up fast, and performance degrades as it fills.
如果你用 Claude Code 做过真实项目，大概率经历过这种事：
问题不全在模型，真正出问题的是一个容易被忽视但很重要的：上下文（Context Window）
Claude Code 官方文档反复强调 context window，但很多人仍然把它当成“聊天长度限制”
实际上，它更像是一种会被污染、会老化、需要管理的工程资源。
如果你已经用过 Agent，可能会有一种很真实的感觉：
好像是会用了，但真让我讲清楚 Agent 是怎么跑起来的，又有点说不明白。
比如：
很多时候，我们是跟着框架把 Agent 跑通了。
可一旦遇到下面这些情况，就会开始有点卡：
这时候你大概率会觉得：Agent 有点像黑盒。
但其实，Agent 真没那么复杂。
如果你愿意把框架先放一边，只看最底层的 API，就会发现：
Agent 本质上，就是几个很普通的东西，被我们拼在了一起。
这篇文章想做的事情也很简单：
不用任何 Agent 框架，只用基础API + Java，一步一步把 Agent 是怎么工作的“摊开来看”。
不追求花哨，只追求你看完之后能说一句：“哦，原来 Agent 是这么回事。”
那我们直接开始。
过去两年，大模型能力的提升有目共睹。
对话越来越自然，推理能力不断增强，看起来几乎“无所不能”。
但在真实的工程实践中，很多人都有类似的感受：
Demo 很惊艳，真正落地却并不轻松。
问题往往不在模型能力本身，而在于：
我们仍然在用早期的工程抽象，承载已经高度复杂的 AI 能力。
本文尝试从工程视角，回顾 AI 应用从「对话」到「Skills」的演进路径。