个人网页

我们开发的每一个需求，基本 80% 的时间在搞清楚该改什么，只有 20% 在写代码。这不是能力原因，更是在于软件的复杂度 一个似曾相识的场景 比如接到需求：结算单状态机增加一个「部分退款」中间状态 在梳理了 SettlementService、SettlementController、SettlementStateMachine 后，改动范围很清楚——加一个枚举值，改三条状态流转路径。改动量很小，代码 review 也顺利通过。 结果上线第二天，告警来了：对账报表里部分退款的结算单被重复计入 问题出在一个没人知道的类——ReconciliationReportBuilder。它内部有一个 switch-case 遍历结算单状态来决定归入哪个科目，新增的枚举值走到了 default 分支，被当成「已结算」处理了 这个类的存在，在改代码的时候可能完全不知道。甚至不知道「我应该知道它的存在」 如果你在接手业务需求的时候也踩过类似的坑，这篇文章就是写给你的 复杂度不是代码行数多，而是「改起来费劲」 先澄清一个常见的误解：复杂度 ≠ 功能多、代码量大。 一个 50 万行的系统，如果你...

AI 编程助手已经越来越常见。很多人会用 Claude Code、Cursor、Codex CLI 这类工具来读代码、改代码、解释架构、定位 bug。 但 AI 经常会遇到一个问题，尤其是项目比较大的时候：它并不是真的掌握了整个代码库的结构，而是在不断搜索文件、读取文件、猜测关系。 比如你问：这个请求最后是怎么走到数据库查询的？ 如果没有更好的索引，AI 可能会从 route 开始搜索，打开几个 controller，再继续找 service、model、query builder。过程中它会消耗很多 token 和工具调用，而且一旦漏掉某个框架约定或隐式调用，结论就可能不完整。 而 CodeGraph 要解决的，就是这个问题。它为代码库建立一个本地的代码知识图谱，让 AI 编程助手可以直接查询代码结构，而不是每次都从零开始翻文件。 CodeGraph 是什么 CodeGraph 是一个面向 AI 编程助手的本地代码智能工具。 它会扫描项目，解析代码里的函数、类、方法、组件、路由、导入关系和调用关系，并把这些信息保存到本地 SQLite 数据库中。之后，AI agent 可以通...

最近在读 Superpowers 里的一个 skill：subagent-driven-development。 这个 skill 很有意思。它并不是教 agent 如何写某一种代码，而是在设计一种开发流程（开发+review）：当我们已经有一个实现计划，并且计划里的任务相对独立时，主 agent 不再亲自完成所有工作，而是把每个任务派发给新的 subAgent，再通过两阶段 review 来控制质量。 它的核心思想可以用一句话概括： 每个任务派一个新的 subAgent + 两阶段审查 = 可控、高质量、低上下文污染的开发流程。 也就是说，它真正关注的不是「让更多 agent 干活」，而是「如何让多个 agent 在明确边界内协作」。 一、 它解决的不是编码问题，而是协作控制问题 在 SKILL.md 里，开头就定义了这个 skill 的执行方式： 123Execute plan by dispatching fresh subagent per task,with two-stage review after each:spec compliance review fi...

AI Coding 目前已经成为标配，但现实是有的团队效率提升 3 倍，有的团队却效果一般。问题不在 AI，而在使用方式。 一、为什么 AI Coding 会让代码变乱？ 很多人把 AI 当成「更聪明的程序员」：帮我实现一个XX功能， 然后会得到一段「看起来没问题」的代码 但这种方式的问题在于： AI 不知道系统结构 不知道业务约束 不对最终正确性负责 它只是基于已有上下文，生成一个「自洽的结果」，而这个结果就是：代码能运行，但是很多功能偏离预期或者边界未处理 所以关键不在于AI 能不能写代码，而在于：你有没有能力约束 AI 写出满足需求的代码 二、AI Coding 工程模型（4C + 1V） 真正有效的 AI Coding，不是写 Prompt，而是一个工程模型： 12345Context（上下文控制）Task（任务拆解）Constraint（约束注入）Checkpoint（过程控制）Verification（结果验证） 这五个能力不是并列关系，而是一条执行链路： 1Task → Context → Constraint → Checkpoint → Verificati...

当前，AI 的自动化「实现能力」正在迅速增强，代码生成、逻辑补全、测试构建，已经不再是主要瓶颈 目前真正决定效率上限的，正在变成：我们是否能够清晰地定义任务、边界和验收标准 当这些被完整定义后，AI 就可以自动完成实现、验证与修复，直至满足规格约束 这场变化不再是工具升级，而是工程能力结构的迁移。而规范驱动开发，正是这种迁移的实践形式 一、规范驱动开发的核心定义 规范驱动开发可以简单理解为：将需求转化为结构化规格（Specification），以规格作为唯一可信来源，由 AI 负责实现与验证 它包含三个部分：规格定义、验证设计、实现执行，人主要负责前两部分，而 AI 来负责第三部分 二、规范驱动开发的五步操作框架 第一步：问题结构化 目标：将模糊需求转化为可执行任务单元 也就是将需求描述清楚，可以让AI 明确我们要做的功能，主要包括： 将需求拆分为独立场景 明确输出与输出极其格式 去除模糊的表达并进行量化 错误示例：：优化一下性能 结构化表达：在总数据量为 100 万的情况下，接口 TP999 响应时间 ≤ 200ms 如果无法结构化，说明问题尚未定义清楚 第二步：规格建模...

在工程讨论中，一旦提到「大模型应用开发」，立即就会出现一大堆的概念：LangChain / LangGraph、Agent Loop、Tool Calling、Memory 管理、Planning 策略、Orchestration 等等 但现实项目中，大量需求并没有复杂到需要构建运行时系统，很多场景只是希望可以封装一个能力、提供一个结构化的交互，同时可以被稳定复用 对于这类问题，更务实的路径是：不要从零构建 Agent，而是基于通用Agent 进行扩展 —— 通过编写Skills 本文将通过一个真实示例说明，如何仅通过定义一个 Skill，就实现一个完整可用的小型大模型应用 Agent Skills 在应用生态中的位置 理解 Skills 的价值，需要把它放在更大的构建路径坐标系中，大模型应用开发大致存在三种层级方式： Prompt级使用 基本都是单次交互、行为无结构、难以复用且不具备应用形态 适合探索，但难以工程化 Skills 扩展（本文关注） 用来定义能力行为，可以描述交互流程，能被 Agent 自动调度，同时可复用与迭代 其本质变化是：我们不再编写 Prompt，而是在...

引言：那个熟悉的念头 在把一件事交给 AI 之前，我们心里往往有一个隐含期待：“它应该能帮我省点事” 但实际操作中，流程通常是：先解释背景，再说明目标，中途补充"之前没写清楚但很重要"的约束，等 AI 给出结果后，开始修改、校对、推翻重来。做到一半，一个念头会自然浮现： “这件事，我是不是自己来反而更快？” 如果你有过这种感觉，先别急着怀疑 AI，也别急着怀疑自己。更可能的问题是：我们一开始就在问一个不太对的问题 第一部分：为什么"选什么任务交给 AI"并不能真正解决问题 团队引入 AI 的早期，几乎所有讨论都会集中到同一个问题上：哪些任务适合交给 AI？ 这个问题听起来理性且工程化，但很多团队很快会发现一个尴尬现实：同样的工具、同样的模型，有人觉得特别好用，有人觉得不过是"高级搜索"，效果极不稳定。 这通常不是因为"任务选错了"，而是因为——我们混淆了"工具适配"与"协作设计"这两种完全不同的逻辑 1. 我们为什么会这样问？ "选任务"的...

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，但很多人仍然把它当成“聊天长度限制” 实际上，它更像是一种会被污染、会老化、需要管理的工程资源。 重新理解 Context Window Context Window 不只是聊天记录，在 Claude Code 中，Context Window 包含： 整个对话历史 Claude 读过的所有文件 每条命令的执行结果 所有失败尝试、中间结论和被推翻的假设 这些内容不只是被动记忆，而是会作为持...

如果你已经用过 Agent，可能会有一种很真实的感觉： 好像是会用了，但真让我讲清楚 Agent 是怎么跑起来的，又有点说不明白。 比如： Agent 为什么能一边“想”，一边“用工具”？ Function Call 到底是谁在调用？模型？还是我们？ LangChain / LangGraph 里那些节点、Memory，看起来很高级，本质在干嘛？ 很多时候，我们是跟着框架把 Agent 跑通了。 可一旦遇到下面这些情况，就会开始有点卡： 想自己手写一个简单 Agent 想排查 Agent 为什么卡住、不动了 或者想做点框架里没有的定制逻辑 这时候你大概率会觉得：Agent 有点像黑盒。 但其实，Agent 真没那么复杂。 如果你愿意把框架先放一边，只看最底层的 API，就会发现： Agent 本质上，就是几个很普通的东西，被我们拼在了一起。 这篇文章想做的事情也很简单： 不用任何 Agent 框架，只用基础API + Java，一步一步把 Agent 是怎么工作的“摊开来看”。 不追求花哨，只追求你看完之后能说一句：“哦，原来 Agent 是这么回事。” 那我们直接开始。...

过去两年，大模型能力的提升有目共睹。 对话越来越自然，推理能力不断增强，看起来几乎“无所不能”。 但在真实的工程实践中，很多人都有类似的感受： Demo 很惊艳，真正落地却并不轻松。 问题往往不在模型能力本身，而在于： 我们仍然在用早期的工程抽象，承载已经高度复杂的 AI 能力。 本文尝试从工程视角，回顾 AI 应用从「对话」到「Skills」的演进路径。 一、只能对话的 AI：语言生成阶段 最早一批 AI 应用，本质上可以抽象为：Prompt + Model = 一个“超级文本接口” 它们擅长： 问答 翻译 总结 多轮对话 在工程上，这类系统通常具备几个特征： 无状态或弱状态 不依赖外部系统 非常容易做出 Demo 但它们也有一个根本性的限制：AI 只能“说”，不能“做”。 一旦需求从“回答问题”升级为“完成任务”，这种形态很快就会触顶。 二、推理能力增强：AI 开始“像人一样思考” 随着推理能力的增强，AI 开始具备： 多步推理能力 任务拆解能力 条件判断和规划能力 这使得 AI 看起来不再只是“生成答案”，而是在解决问题。 然而，工程实践很快暴露出新的边界：...