一、破局：AI 编码的真正瓶颈不是模型，是上下文管理

在软件开发的历史进程中，每一次效率的飞跃都伴随着抽象层次的提升。从汇编语言到高级语言，从手动内存管理到垃圾回收，开发者始终在寻求降低认知负荷的方法。进入 2026 年，生成式人工智能（GenAI）已成为编程领域不可或缺的力量。 然而，行业正经历从 “模型崇拜” 向 “工程落地” 的深刻转型，单纯依靠增加大语言模型（LLM）的参数规模已无法解决复杂业务逻辑中的幻觉与失控问题。

当前的共识是，AI 编码（AICoding）的真正瓶颈不在于模型的逻辑能力，而在于上下文管理（Context Management）的失效与开发意图（Intent）的模糊。

通过对 Anthropic 推出的 Claude Code（以下简称 CC）与 Fission AI 倡导的 OpenSpec 进行深度解构可以发现，两者正在通过 “代理化执行” 与 “规格化驱动” 双轮驱动，构建一套闭环的 AI 研发体系。这种结合不仅标志着 AI 编程工具从 IDE 插件向终端原生代理（Agentic Tool）的转变，更预示着 “规格驱动开发”（Spec-Driven Development, SDD）将成为企业级 AICoding 落地的核心范式。

在 AICoding 的早期阶段，开发者普遍认为只要模型足够强大，就能解决所有编程难题。然而，随着项目复杂度的增加，这种观点遭到了现实的挑战。研究表明，虽然 AI 编码助手的使用率在提升，但软件交付的稳定性却在下降。例如，Google 的 DORA 2024 报告指出，AI 采用率每增加 25%，交付稳定性反而下降 7.2%。

生产力悖论与认知负荷

AICoding 领域存在一个显著的 “生产力悖论”：开发者在使用 AI 时主观感知速度提升了 20%，但实际完成任务的时间却增加了 19%。这一现象的根源在于 AI 在处理长上下文时的效能衰减。随着任务推移，AI 往往会陷入修正循环（Fix/Test Loops），无法触及深层的业务功能，反而需要更多的人工干预。

模型的逻辑推理能力（Reasoning）在短小上下文中表现卓越，但在大型工程环境中，模型面临的是 “上下文中毒”（Context Poisoning）和 “注意力漂移”（Attention Drift）。当对话历史过长或包含过多无关代码时，模型的性能会呈现非线性下降。例如，GPT-4o 等先进模型在 1K Token 时的准确率为 99.3%，而当上下文扩展到 32K Token 时，准确率会暴跌至 69.7%。这种 “性能断崖” 意味着，单纯依靠扩大上下文窗口（Context Window）并不能解决问题。

上下文工程的兴起

上下文工程（Context Engineering）正在取代提示词工程（Prompt Engineering），成为 AICoding 的核心技术方案。上下文工程的核心不在于 “如何写更好的指令”，而在于 “如何为模型筛选最精准的 Token 集合”。

下表对比了传统缩放路径与上下文工程路径的局限性：

在大型组织中，上下文管理面临更严峻的挑战。很多关键决策并未记录在代码中，而是散落在飞书文档评论、群消息、会议或开发者的认知中。AI 代理在缺乏这些隐性知识（Implicit Knowledge）的情况下，生成的方案虽然符合语法，但却违背了架构初衷或业务约束。

上下文作为一等系统

现代 AI 代理架构开始将上下文视为一种具有自身架构、生命周期和约束的 “一等系统”。在这种视角下，上下文管理不再是临时的字符串拼接，而是一条精密的 “编译器管道”：

• 存储与呈现分离： 区分持久化的会话状态（Session）与单次模型调用的工作上下文（Working Context）。
• 显式转换： 通过命名的、有序的处理器（Processors）构建上下文，而非随机堆砌。
• 默认作用域： 每个子代理仅能看到执行任务所需的最小上下文，通过工具（Tools）按需获取更多信息。

二、Claude Code：把 AI 变成真正懂你项目的编码伙伴

Claude Code (CC) 是 Anthropic 推出的原生代理工具，它直接运行在终端中，具备读取文件、运行命令、执行重构以及自主验证的能力。与传统的 IDE 插件相比，CC 的核心优势在于其“代理循环”（Agentic Loop）和对上下文协议的深度掌控。

代理循环：收集、行动与验证

CC 的工作流程被定义为一个闭环系统，旨在模仿人类工程师的思维过程：

• Gather Context（收集上下文）： CC 不会盲目读取整个目录，而是通过文件搜索、Git 状态检查以及读取特定的 CLAUDE.md 文件来建立认知。
• Take Action（采取行动）： 基于推理，CC 可以跨多个文件执行编辑，或者利用终端工具（如 npm install、git commit）操作环境。
• Verify Results（验证结果）： 这是 CC 最具杀伤力的特性。它能自动运行测试、捕捉错误，并根据反馈调整方案。研究表明，带有验证步骤的 Coding 生成过程，其成功率远高于单次生成。

终端原生的工程哲学

CC 选择了终端而非图形界面作为主场，这体现了其 “代理优先” 的设计哲学。CC 遵循 Unix 哲学，支持管道（Pipe）、脚本化和自动化集成。这种设计使得 CC 能够与现有的 CI/CD 流程完美衔接，例如在 GitHub Actions 中自动执行代码审计。Anthropic 最新推出的 Code Review 功能，就是通过 Claude Code 基于 PR 的方式进行 bug 的追踪。

下表详细对比了 CC 与行业领先的 AI 编辑器 Cursor 的差异：

MCP 与“即时上下文”

CC 深度整合了模型上下文协议（Model Context Protocol, MCP）。MCP 是一个开放标准，允许 AI 代理安全地访问外部数据源。

为了应对大规模工具定义导致的上下文溢出，CC 引入了 “工具搜索” 和 “代码执行” 模式。代理不再一次性加载成千上万个 API 定义，而是通过编写代码按需调用 MCP 服务。例如，在分析大型数据库时，CC 不会加载全量数据，而是编写针对性的查询语句，仅将结果摘要读入上下文。这种 “按需加载” 策略极大地提升了 Token 的效用。

CLAUDE.md 与自动记忆

CC 引入了 CLAUDE.md 文件作为项目的 “操作手册”。这是一个置于根目录的 Markdown 文件，用于存储项目特定的编码标准、架构决策和测试指令。与临时提示词不同，CLAUDE.md 提供了持久的、跨会话的约束。

此外，CC 具备 “自动记忆”（Auto Memory）功能。它会自动在 MEMORY.md 中记录项目的构建命令、调试心得和用户的偏好设置。每当新会话启动时，CC 会加载这些记忆的前 200 行，从而确保 AI 在长期协作中能够 “越用越懂你”。

三、OpenSpec：给 AI 编码加上"规格书"，从失控到可沉淀

虽然 Claude Code 提供了强大的执行引擎，但在复杂业务中，AI 仍然可能因为意图不明而跑偏，最终导致交付的代码不符合预期。

OpenSpec 的出现为 AI 编码提供了 “规格说明书”，将 AICoding 从 “凭感觉写代码” 提升到了 “按规格执行任务” 的高度。

规格驱动开发 (SDD) 的兴起

OpenSpec 倡导的是一种 “规格驱动开发”（Spec-Driven Development）范式。其核心理念是：在写任何一行代码之前，先由人类与 AI 共同协商并锁定一份机器可读、人可评审的规格文档。

下表展示了 SDD 的三个演进阶段：

OpenSpec 的工件体系 (Artifacts)

OpenSpec 弃用了笨重的开发文档，转而采用一套轻量级的、面向 AI 优化的 Markdown 工件体系。每个变更（Change）都被组织在独立的文件夹中：

• proposal.md： 描述变更的初衷（Why）和范围（What）。
• specs/： 具体的逻辑规格，通常包含 “Scenario（场景）” 描述，通过具体的输入输出消除模糊性。
• design.md： 技术设计方案，包括本次变更涉及的数据库变更、接口调整等。
• tasks.md： 原子化的任务清单，作为 AI 的执行路径图。

解决上下文污染：提案、应用与归档

OpenSpec 最具洞察力的设计在于其生命周期管理。AI 在处理新任务时，最忌讳被旧任务的陈旧信息干扰。OpenSpec 的 “归档（Archive）” 机制解决了这一问题：

• Proposal 阶段： 建立一个独立的变更上下文，让 AI 只关注当前变更。
• Apply 阶段： AI 严格按照 tasks.md 执行，避免了盲目扫描全库导致的 Token 浪费。
• Archive 阶段： 任务完成后，临时变更文档被移入归档，核心规格更新至主规格文件。这保证了 AI 始终在一个 “卫生” 的上下文环境下工作，同时也为项目留下了可追溯的决策链路。

四 、实战：CC + OpenSpec 如何落地真实业务

在实际的企业业务场景中，如何整合这两大工具？答案在于将 OpenSpec 的标准化指令集注入到 Claude Code 的会话环境中。

案例实战：复杂业务逻辑的重构

假设一个电商项目需要重构其优惠券结算逻辑。在传统的 AI 辅助下，AI 可能会在修改 CouponService.java 时遗漏分布式锁，或者破坏原有的满减叠加规则。采用 CC + OpenSpec 模式，流程如下：

第一步：提案初始化

执行 /opsx:propose "重构优惠券结算逻辑，引入 Redis 分布式锁并支持多卷叠加"。CC 会在 openspec/changes/refactor-coupon-logic/ 下生成整套骨架。AI 会通过分析现有代码，在 spec.md 中自动列出已知的结算场景。

第二步：规格对齐与边界确认

这时不用急着让 AI 写代码，而是需要先审阅 spec.md。如果发现 AI 没考虑 “优惠券过期临界点” 的并发问题，可以直接要求 AI 修改规格：“在 spec.md 中增加过期校验场景，并要求使用 Lua 脚本保证原子性”。

第三步：受控应用（Apply）

一旦规格通过人工评审，就可以执行 /opsx:apply 了。这时，CC 就变成了完美的执行机器。它不再 “猜” 开发者的意图，而是对照 tasks.md 逐项实施。每一项修改后，它都会运行相关的测试。如果测试失败，CC 会自动分析错误并重新修复，直到该项 Task 标为 “完成”。

第四步、归档与知识固化

任务结束后，执行 /opsx:archive。原本散落在会话记录中的重构逻辑，现在变成了 openspec/specs/coupon-settlement.md 中的标准规格。当下一次另一个 AI 代理（或新入职同事）需要修改此模块时，它只需读取这份规格，即可获得完整的业务语境。

工具链对比：为何选择 OpenSpec

在 SDD 工具链中，OpenSpec 展现出了极高的工程性价比：

OpenSpec 的优势在于它不试图改变开发者的工具偏好。无论是使用 Claude Code、Cursor 还是 Aider，都可以无缝接入 OpenSpec 的规格管理层。

五、沉淀：让 AI 编码能力在团队中持续积累

AICoding 落地的终极目标不是让个体开发者写得更快，而是提升整个团队的知识资产质量。AI 编码能力不应随对话窗口的关闭而消失，而应作为 “团队记忆” 沉淀下来。

从个人技能到组织技能

团队可以通过自定义 Skill 和 MCP Server 来固化组织资产。

• Skill： 将公司特有的代码风格、安全审计清单，或者特定中间件的使用指南封装为 .claude/skills/。当团队成员使用 CC 时，AI 会自动加载这些技能，仿佛有一位资深架构师在时刻盯着每一行代码。
• MCP Server： 连接企业内部的向量数据库（如基于 Zilliz 的语义搜索），让 AI 代理能够从数千万行历史代码中找到最佳实践。

建立 AICoding 效能飞轮

AICoding 的成功落地需要建立一套正向循环的 “飞轮”：

• 规格积累： 每完成一个 PR，都强制更新对应的 OpenSpec 规格文件。
• 指令进化：发现 AI 反复犯的错，就将其转化为 CLAUDE.md 中的负向约束（Prohibited rules）。
• 并行执行： 利用 CC 的 Agent Teams 能力，让一个代理负责写规格，另一个代理负责审计代码，第三个代理负责集成测试。

角色转变：从 “码农” 到 “规格定义者”

在 CC + OpenSpec 模式下，软件工程师的角色正在发生质变。如果 AI 能够根据完美的描述生成任何代码，那么 “代码” 本身就变成了编译后的中间产物，而 “规格” 才是核心产品。领域专家（Domain Experts）的重要性显著提升，因为他们能提供最高质量的业务意图描述。这种趋势将迫使开发者从关注 “语法实现” 转向关注 “系统设计” 和 “逻辑严密性”。

六、结语：AICoding 落地的飞轮正在转动

在 2026 年，AICoding 已不再是科幻。Claude Code 提供的强大代理能力，配合 OpenSpec 提供的精密规格框架，为企业提供了一套可复制、可量化的研发新范式。

我们必须承认，AI 编码的瓶颈从来不是模型不够聪明，而是我们与 AI 之间的 “沟通带宽” 太低且 “上下文” 太脏。通过上下文工程化管理（CC）和意图标准化表达（OpenSpec），我们正在构建一套让 AI 能够长期、稳定产出的工程环境。

随着这一模式的普及，软件开发的门槛将进一步降低，而创新的上限将被无限拉高。AICoding 落地的飞轮已经转动，那些能够率先将 AI 编码能力转化为团队组织资产的企业，将在未来的数字化竞争中占据绝对的先机。毕竟，在 AI 时代，掌握了 “意图” 与 “上下文” 的人，才掌握了软件工程的未来。

参考文档：

1. thenewstack.io/context-is-…
2. github.blog/ai-and-ml/g…
3. solguruz.com/blog/spec-d…
4. medium.com/@eran.swear…
5. www.anthropic.com/engineering…
6. code.claude.com/docs/en/how…
7. www.anthropic.com/engineering…
8. code.claude.com/docs/en/bes…
9. dev.to/webdevelope…

往期回顾

1.大禹平台：流批一体离线Dump平台的设计与应用｜得物技术

2.基于 Cursor Agent 的流水线 AI CR 实践｜得物技术

3.从IDE到Terminal：适合后端宝宝体质的Claude Code工作流｜得物技术

4.AI编程能力边界探索：基于 Claude Code 的 Spec Coding 项目实战｜得物技术

5.搜索 C++ 引擎回归能力建设：从自测到工程化准出｜得物技术

文 /后羿

关注得物技术，每周更新技术干货

要是觉得文章对你有帮助的话，欢迎评论转发点赞～

未经得物技术许可严禁转载，否则依法追究法律责任。

一、背景

事情是这样的，之前对 AI 编程一直是观望态度，但是部门最近在做 AI 辅助编程 POC，有幸成为 POC 用户，用上了自己舍不得买的高级编程模型 （感谢公司）。尽管我自认为是一个在代码上很挑剔的人，但是试了下感觉居然还可以 （Go、React）！只能说还得是谷歌，调整重心略微发力，Gemini 3 表现确实很不错。既然尝到甜头了，觉得自己是时候好好地琢磨琢磨，研究研究，沉淀一套自己的工作流、方法论，解放自己的生产力，顺应潮流努力成为 AI 时代的受益者，而不是被淘汰的人！

新的开发范式需要搭建新的开发环境和匹配自己开发习惯的工作流，这就像刚学编程那会，需要挑一个自己喜欢的 IDE、熟悉 IDE 快捷键和优化 IDE 设置一样。过程中间肯定有阵痛，Java 开发者们回忆一下多年之前从 Eclipse 转 IDEA 那会的阵痛吧，但是磨刀不误砍柴工，阵痛之后一定是生产力提升。借本文分享下我摸索后的方案，供大家参考。

二、工具选型

目前 AI 辅助编程领域热火朝天，各种 GUI 工具、TUI 工具如雨后春笋让人目不暇接，这对于花心的强迫症选手（比如我）来说选型很困难。但是我觉得有两个基础认知可以帮助我们更好地做决定：

（一）AI 辅助编程工具由脑和手两部分组成。脑是外接的大模型 API，手是各个产品调教的提示词和内部工作流。按我理解，【脑】决定了工具的上限，【手】决定了工具的下限。在这个场景里，大模型就像是汽车里的发动机，而且所有型号的汽车支持的【发动机】规格都是通用的、统一的、标准化的。有了这个基础，我们可以随便选一个趁手的工具，然后自行按场景选配【合适】的【发动机】。

（二）AI 辅助编程当前是一个【千帆竞发】的热门领域，而且单纯就【工具】来说，这个领域【没有技术壁垒】。A 产品抛出的杀手级特性，不出半个月一定会有 B 产品跟进。毕竟现在软件迭代的速度借助 AI 提升了很多，A 产品验证过的想法，B 产品可以很快地跟进和实现。Claude Code CLI 的开发者就使用 Claude Code CLI 迭代 Claude Code CLI，有点绕口，大概就是【工具自举】的意思吧。

Claude Code CLI

综上，其实没啥纠结的，我们照着这两点来选型就好：1. 这个工具一定得便捷地支持模型插拔，就是我随时可以根据场景换一个更适合的、更便宜的、表现更好的大模型。而且这种插拔一定要简单。 2. 这个工具一定要有积极的维护者，不断地迭代、优化它的工作流、提示词。最好是一个商业化产品，因为商业化产品出于其商业目标，一定会投入资源积极进行迭代。 

当前满足这两个条件的，我想也就是 Claude Code CLI 了： 1. Claude Code CLI 是一个商业化产品，有专门的技术团队在不停地更新、迭代。 2. Claude Code CLI 可以非常便捷地支持大模型插拔，我可以随时根据成本、效率、体验来切换合适的大模型。因此，这个环节我选 【Claude Code CLI】。

后文以CC代指Claude Code CLI。

快速切换模型

我通过自定义 Shell 函数来实现便捷的模型切换，不同的场景、不同的任务使用不同的模型。基本原理就是，CC 支持环境变量注入 LLM 配置信息，因此我只需要按场景注入【行内临时环境变量】即可。

详见：Bash - 行内环境变量，Bash 是标准的 Shell 实现，其他 Shell 如 Zsh 都兼容其行为。

Shell配置

我到处弄了一堆免费的、收费的模型用，然后给他们取了我记得住的别名：

使用效果

为了兼容，设置了一个 claude 别名：

这样输入claude 时，默认使用智谱 GLM 模型。

脚本源码

Shell 脚本大概这样，可以修改后配置到自己的 ~/.zshrc 中。如果不熟悉 Shell，嫌麻烦也可以试试这个开源工具：farion1231/cc-switch。

# claude 默认
alias claude='zcc'
# Kimi
function kcc(){
    echo Kimi Claude Code...
    local model="kimi-k2.5"
    ANTHROPIC_BASE_URL="https://api.moonshot.cn/anthropic" \
    ANTHROPIC_AUTH_TOKEN="sk-xxxxxxxxx" \
    ANTHROPIC_SMALL_FAST_MODEL="$model" \
    ANTHROPIC_DEFAULT_OPUS_MODEL="$model" \
    ANTHROPIC_DEFAULT_SONNET_MODEL="$model" \
    ANTHROPIC_DEFAULT_HAIKU_MODEL="$model" \
    CLAUDE_CODE_SUBAGENT_MODEL="$model" \
    launch_claude_code $@
}
# 智谱GLM
function zcc(){
    echo GLM Claude Code...
    ANTHROPIC_BASE_URL="https://open.bigmodel.cn/api/anthropic" \
    ANTHROPIC_AUTH_TOKEN="sk-xxxxxxxxx" \
    launch_claude_code $@
}
# 七牛
function qcc(){
    echo QiNiu Claude Code...
    local model="minimax/minimax-m2.1"
    ANTHROPIC_BASE_URL="https://api.qnaigc.com" \
    ANTHROPIC_AUTH_TOKEN="sk-xxxxxxxxx" \
    ANTHROPIC_SMALL_FAST_MODEL="$model" \
    ANTHROPIC_DEFAULT_OPUS_MODEL="$model" \
    ANTHROPIC_DEFAULT_SONNET_MODEL="$model" \
    ANTHROPIC_DEFAULT_HAIKU_MODEL="$model" \
    CLAUDE_CODE_SUBAGENT_MODEL="$model" \
    launch_claude_code $@
}
function launch_claude_code(){
    CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 \
#    clear
    command claude $@
}

三、开发环境

在当前的气氛下，我想我算是一个【古板】的开发者，我做不到【fire and forget】，或者说完全靠黑盒的自然语言对话来完成代码开发。

我还是只将 AI 当助手，还是想要白盒的掌控 AI 写的代码，还是希望最终交付的代码有我的风格、我的审美、我的品味。毕竟 AI 也只能帮我写代码，并不能帮我背锅。尽管我选择了 TUI 工具 Claude Code CLI，但是我还做不到全程只在终端操作，我还是习惯 JetBrains 特色的双栏 diff。

因此，当前我开发流程的起点还是传统的 IDE，比如我最喜欢的 JetBrains。每天上班第一件事是接水，第二件事就是打开 IDE。所以我需要想办法来将 GUI 工具和 TUI 工具流畅的衔接起来，减少代码开发时的频繁切换产生的割裂感！

多屏协作

如上图，我有 3 个显示器，我的构想是这样的：

1. MacBook 内置显示器 —— 常驻两个空间：一个用来打开浏览器，还有 VPN、网易云音乐、Finder 软件，用来承接各种临时的操作。一个用来打开飞书，用来沟通、协作。

2. 中间主屏 —— 常驻两个空间：一个用来打开浏览器，用来做各种【输出】。一个用来打开 IDE，专注于写代码、看代码，用标签页打开多个 Project。

3. 左边竖屏 —— 常驻两个空间：一个用来打开浏览器，用于看文档、查资料等各种【输入】。一个用来打开 TUI 工具，进行辅助编程！

GUI/TUI衔接

现在问题来了，我希望我的开发工作的【主轴】是 IDE，流程的起点是 IDE。但是我的 IDE 在中间屏幕，终端在左边屏幕，它俩是独立软件，没法协作、自动跟随切换 Project 的工作目录。我希望有个【自动化流程】，当我在 IDE 里切换项目的时候，CC 自动跟随切换！

衔接流程

我期待的流程是这样的：

因为某个原因，我在 IDE 里打开了一个项目 A → 准备写代码了，点击 IDE 里的某个【按钮】，左边屏幕自动【新建】一个项目 A 的 CC 会话终端并激活到前台显示  → 我跟左边的 CC 对话，让他干活 → 我在中间的 IDE 里评审、调试、诊断 → 因为某些原因我又要在 IDE 打开一个别的项目 B → 我再次点击那个【按钮】，左边屏幕自动【新建】一个项目 B 的 CC 会话终端并激活到前台显示 → 我在 IDE 里又切回了项目 A，我又点击了那个【按钮】，左边屏幕自动【切换】到 A 的 CC 会话终端并激活到前台显示。

好的想法已经有了，AI 时代就怕你没有想法，有想法就一定有办法实现！

代码实现

1. macOS 上的原生软件，大部分支持 AppleScript 自动化，也就是说我们可以写脚本驱动软件的行为、模拟人机交互，比如打开软件、新建 tab、点击按钮等。

2. JetBrains IDE 支持集成外部命令，也就是说：可以在 IDE 里点击一个按钮，自动执行一个 Shell 脚本或者别的可执行文件。

产品需求清晰了，接下来开始让 AI 干活！一顿沟通和调试之后，我们有了一个【自动化】创建 iTerm2 新标签的可执行脚本！

这是给大模型的需求提示词，大家可以按需选用，做个性化的调整：

## 📌 工具功能说明
请帮我创建一个 macOS 上的 iTerm2 自动化工具,主要功能包括:
### 核心需求
1. **智能窗口管理**:自动使用或创建 iTerm2 窗口
2. **项目标签管理**:为每个项目目录维护独立的标签页,支持标签复用
3. **三面板布局**:自动创建固定的三面板布局(上方一个全宽面板,下方两个并排面板)
4. **命令自动执行**:在每个面板中自动切换到项目目录并执行预定义的命令
### 使用场景
```bash
# 基本用法:在当前目录打开
./open-claude-in-iterm.sh
# 指定项目目录
./open-claude-in-iterm.sh /path/to/project
```
---
## 🎯 技术架构要求
### 技术栈
- **Shell 脚本** (open-claude-in-iterm.sh):参数处理、路径规范化、日志管理
- **AppleScript** (open-claude-in-iterm.applescript):iTerm2 自动化核心逻辑
- **依赖**:macOS、iTerm2、Bash
---
## 📋 详细功能规格
### 1. Shell 脚本 (open-claude-in-iterm.sh)
#### 参数处理
- **参数1**:项目目录(可选,默认当前目录)
- **自动处理**:相对路径转绝对路径
#### 面板命令配置
```bash
PAN1_CMD="claude"     # 上方面板命令
PAN2_CMD="claude"     # 左下面板命令
PAN3_CMD="claude"     # 右下面板命令
```
### 2. AppleScript (open-claude-in-iterm.applescript)
#### 主要流程
**步骤1:窗口管理**
- 检查 iTerm2 是否运行(未运行则自动启动)
- 使用当前激活的 iTerm2 窗口,如果没有则创建新窗口
**步骤2:标签管理(关键逻辑)**
- 在找到的窗口中,查找 `session.path` 变量等于项目目录的标签
- **复用逻辑**:如果找到现有标签 且 窗口不是新创建的 → 直接切换标签并返回
- **创建逻辑**:如果未找到标签 或 窗口是新创建的 → 创建新标签和布局
**步骤3:三面板布局创建**
```
布局示意图:
┌─────────────────────────┐
│   上方面板 (全宽)         │
│   执行: PAN1_CMD         │
├──────────────┬──────────┤
│  左下面板    │  右下面板 │
│  PAN2_CMD   │  PAN3_CMD │
└──────────────┴──────────┘
```
**分割顺序(重要)**:
1. 初始状态:一个全屏 session(上方面板)
2. 第一次分割:对上方 session 执行**水平分割**,创建下方面板
3. 第二次分割:对下方 session 执行**垂直分割**,创建右下面板
**步骤4:命令执行**
在每个面板中依次执行:
1. 切换到项目目录:`cd "/path/to/project"`
2. 清屏:`clear`
3. 等待 0.3 秒(确保目录切换完成)
4. 执行命令:`PAN_CMD`
5. 等待 0.5 秒(确保命令启动)
## ⚠️ 常见错误
- ❌ 符号链接未处理,导致找不到 AppleScript 文件
- ❌ 分割顺序错误,导致布局不正确
- ❌ 缺少 delay,导致命令执行失败或在错误目录执行
- ❌ 新窗口处理错误,导致多余空白标签
- ❌ 标签复用逻辑错误,导致同一项目创建多个标签
- ❌ 路径未引用,导致包含空格的路径失败

IDE配置

创建外部工具

添加到工具栏

使用效果

点击工具栏按钮后，自动在全屏的 iTerm2 窗口新建或激活项目目录下的 CC 会话，下图里就是 3 个项目。

四、多Agent协作

会的越多，让你干的就越多。既然 AI 那么牛，一个 CC 会话已经满足不了我膨胀的想法和需求了。我希望我可以同时支配多个 AI 开发工程师，而我变成 PM！所以参考酒米的思路，我给每个项目的终端，自动化的划分了 3 个子窗口，每个子窗口都是一个 CC 会话。效果大概这样：

主从架构

每个项目自动打开 3 个常驻的 AI 会话，我设想的工作流是这样的：

【架构师】上面的大屏，用贵的模型！专门用来跟我聊需求、对方案、产出任务列表。

【开发者】下面的两个小屏，用领域特定的模型，专门用来落地大屏架构师产出的方案和任务。比如前端需求用前端效果好的模型，后端需求用后端效果好的模型。

知人善用才是好 PM！这个模式也很匹配现实中的组织架构和成本取舍，现实中每个需求一般也都是由一个架构师和多个中高级开发者来协作完成！感谢热心市民无声雨，给我们小组共享了自己采购的纯血 Claude 模型，所以目前我用 Claude 模型来对方案，用 GLM 或者 MiniMax 来实施方案！

规范驱动开发(SDD)

主从智能体的协作很重要，我跟【架构师】聊了半天确定的方案和设计，需要有一个清晰的、对大模型友好的方案和任务文档作为【开发者】的输入。这就很巧，刚好最近在流行 SDD，规范驱动开发。大致就是模拟现实中的软件开发流程将开发生命周期拆分为 3 个阶段：

• 【proposal】需求对齐、方案设计、【任务细化】；
• 【apply】开发任务实施；
• 【archive】功能验收、文档沉淀

围绕这个流程，开源社区设计和研发了一系列对大模型非常友好的工具和提示词（比如 OpenSpec），【阶段 1】和【阶段 2】中间通过格式设计良好的【设计文档和任务文档】来进行上下文交接。

也就是说，我可以在上述的 3 窗口环境中，按照 SDD 流程来：【proposal】跟【架构师】交互，对齐需求、设计和任务 A → 【apply】让【开发者 1】着手完成任务 A → 【proposal】继续跟【架构师】交互，对齐需求、设计和任务 B → 【apply】让【开发者 2】着手完成任务 B → 【proposal】继续跟【架构师】交互，对齐需求、设计和任务 C → 【apply】让【开发者 1】着手完成任务 C → ……

五、CC拓展

CC 当然很厉害，但它本质上也就是一个朴素的 ReAct 模式智能体。

ReAct 这么火，大家肯定也都耳熟能详了，我们也就不说太多。当然 CC 团队围绕编程这个课题做了很多细致的提示词调优和内置工作流设计，这个我们黑盒的用就好了，也没必要关注太多。我们最需要关注的，是 CC 提供给我们使用者的【拓展点】，那些允许我们个性化设置的东西。

命令(command)

命令的本质就是预定义的提示词模板。目的是为了省事，不用每次都重复的输入类似的提示词。比如想让 CC 帮我提交代码，每次我们可能都要交代一大堆字，比如：

请调用 git diff --cached 获取当前暂存区的代码变动。
忽略所有的 node_modules 或二进制文件。
基于变动内容，判断这是一个 feat (新功能), fix (修复) 还是 chore (杂务)。
生成一个不超过 50 字符的标题，并在正文详细列出影响的文件。
由我确认后执行 git commit。”

就像写代码的时候将重复代码提取为一个独立方法一样，我们可以把这些可以复用的提示词固定成一个【命令】，后续使用的时候，直接输入命令名字就好。斜杠命令是一段提示词的快捷方式。

技能(skill)

技能和命令最大的差别就是：命令是用户主动提交的提示词，而技能是 Agent 自己决策后自动导入的提示词。当然技能包里除了提示词，一般还会携带一些配套的工具、脚本、命令或者文档。

比如，我安装了一个【html 转 pdf 的技能包】，这只能提示 CC 可以使用这个技能，但是具体用不用、什么时候用、怎么用都是 CC 自己规划、决策的。

子代理(subAgent)

SubAgents 是可以并行处理任务的独立 AI 代理，每个子代理拥有独立的上下文窗口，可以分配不同任务以提高效率。【主代理】的上下文窗口中包含有【子代理】的【简短】描述信息，可以基于这个描述信息规划、决策使用哪个子代理。

{
  "agents":{
    "code-reviewer":{
      "description":"专门负责代码审查的子代理",
      "model":"claude-opus-4-5",
      "instructions":"你是一个专业的代码审查专家,专注于检查代码质量、安全漏洞和性能问题。",
      "tools":["read","search","git"],
      "permissions":{
        "allowWrite":false
      }
    },
    "test-writer":{
      "description":"专门负责编写测试的子代理",
      "model":"claude-sonnet-4-5",
      "instructions":"你是一个测试工程师,专注于编写全面的单元测试和集成测试。",
      "tools":["read","write","bash"]
    },
    "doc-generator":{
      "description":"专门负责生成文档的子代理",
      "model":"claude-sonnet-4-5",
      "instructions":"你是一个技术文档专家,专注于生成清晰、准确的技术文档。",
      "tools":["read","write"]
    }
  }
}

独立上下文窗口的好处是：避免上下文污染和占用。比如我要在代码里找一个接口的所有实现类，这个就很适合子代理来做。主代理只需要交代给子代理接口名，然后就等子代理返回实现类列表。

这样在主代理的上下文窗口里，只会有子代理的输入和输出（几个类文件路径），而子代理在搜索过程中遍历文件、目录、读取文件内容产生的临时 token，不会对主代理产生影响。我目前认为 SubAgent 和 Skill 差不太多。不过我不确认 Skill 是不是在独立的上下文中执行。

MCP

MCP 和技能一样，都是由 CC 自主规划、决策使用的。差别有两个：

1. MCP 工具的说明信息占用的上下文太多了！不管是否被使用，每次都需要一口气提交所有工具的完整元信息（使用说明 + 出入参 Schema）供大模型规划、决策，占用大量上下文。而【技能】选择了【渐进式披露】，先向大模型提供少量关键信息，只有在大模型选择了使用技能时，才告诉大模型更多关于技能的补充说明信息，让大模型进一步推理、决策。

2. MCP 工具更多的偏向【远程 RPC】，基于网络来实现原子化的远程能力调用。而【技能】更多的偏向【本地 IPC】，具体能力更多通过【编排】本地脚本、本地命令来实现，有点像 stdio 模式下的 MCP。

钩子(hook)

hook 是在特定事件触发时自动执行的脚本，用于自定义工作流、拦截危险操作、自动格式化代码等。就类似 Linux NetFilter，CC 在很多地方植入了流程执行的劫持点，将流程上下文交给用户开发的脚本或者命令。

插件(plugin)

plugin 就是上述各种拓展打包、分发、安装的一种格式。你可以把它想象成 npm 包、pip 包、apk 包等我们比较熟悉的概念。然后我们可以按流程和格式建设插件市场，类似 pip-index、npm-index 等。

我没有细看流程和格式，但是大概也就是一个特定文件布局的 zip 文件包，里面有插件描述信息和各类拓展，比如可以包含：

• 5 个 Skills；
• 10 个斜杠命令；
• 3 个 MCP 服务器配置；
• 2 个 SubAgent 定义；
• 若干 Hooks。

六、CC技巧

飞书MCP

飞书官方提供了 MCP，我主要用它来读写飞书文档，蛮好用的，大家可以试试。比如我每周都要在固定目录下创建固定标题格式的【系统巡检文档】，所以我借助飞书 MCP 整了个自定义 Command 帮我自动创建这些文档去除重复劳动，感觉真香！之前每次都要手动建 3 个文档、选目录、改名字！

@模糊搜索

有时候我们需要精确的告诉 CC，哪个文件需要读或者改，其实不用从 IDE 里复制文件路径，直接在终端里模糊搜索就好了。

WebFetch

CC 默认集成了 WebFetch 命令，就是指定 URL 读取网页内容，这个理论上就是一个本地执行的 curl 命令，没有云端成本，不需要云端协作。但是有个问题：（一）CC 在访问地址之前，会先调用 anthropic.com 的一个风控接口，判断这个网络地址是否有安全风险。（二）政策原因，anthropic.com 会拒绝所有来自中国大陆、香港的请求，风控接口返回 404 或者其他。（三）风控不通过，WebFetch 失败。

在 ~/.claude/settings.json 中添加如下配置，禁用 WebFetch 工具前置的风控检查就好了。

{
  "skipWebFetchPreflight":true,
}

详见：linux.do/t/topic/114…

WebSearch

WebSearch 是需要云端协作的，需要有个搜索引擎服务提供能力。因为我们没有用官方的付费订阅，所以默认的 WebSearch 工具我们用不了，调用 WebSearch 工具得到的结果都是 0。

办法是去找一个免费或者收费的 MCP 服务。免费的我看大家都推荐 Brave<brave.com>，大家也可以找找别的。收费的也有很多，我看智谱的套餐里限量提供了 <联网搜索 MCP - 智谱 AI 开放文档>。也有很多按量付费的，大概几分钱一次，有需要的可以找找。

添加了 MCP 搜索工具后，建议禁用 CC 自带的 WebSearch 工具，不然每次跟大模型交互时，工具信息还会带给大模型，产生额外的 token 开销和推理误判。在 ~/.claude/settings.json 中添加如下配置：

{
  "permissions":{
    "deny":[
      "WebSearch"
    ]
  }
}

iTerm2通知

终端上的任务需要我们输入的时候，可以配置下，让 iTerm2 发出声音和通知。这样我们就不会因为忘记确认操作而阻塞进度。

详见：Optimize your terminal setup - Claude Code Docs

清空上下文

因为我们每个项目都复用一屏内的 3 个子窗口，一般不会重开。为了避免上下文溢出或者之前对话对新任务产生干扰，当我们完成一个任务时，需要及时的执行 /clear 命令，清空上下文，从 0 开始新对话。

如果任务没有完成，但是又不得不 clear，那么可以维护一个自定义命令，在 clear 后提示大模型根据 git status 看到的文件变更快速找回上下文。把 git 状态当作 AI 的 “短期记忆快照”，/clear 只清上下文，不清工作进度。

# Context Catch-up
当前对话已被 `/clear`，请通过 git 状态恢复上下文。
使用方式：
1. 阅读 `git status`（必要时结合 `git diff`）
2. 仅基于文件变更推断正在进行的任务
3. 延续现有实现思路，不要假设额外背景
4. 在未收到明确指令前，先给出你对当前上下文的判断
目标：
- 快速找回任务状态
- 避免旧对话或错误假设干扰新任务

注意力哨兵

在记忆文件里要求大模型扮演一个特别的角色，如果聊着聊着角色行为丢失了，说明大模型注意力失焦了，已经丢掉了你最开始的要求。这时候就该 clear 一下重开会话了。

拓展市场

为了便于相关个性化拓展物料的分发、便于大家搜索、安装，市面上已经有了相关的分发平台和便捷安装命令了。

1. skills.sh

2. www.aitmpl.com

状态行个性化

状态行显示在 Claude Code 会话界面底部，可以自定义显示的内容，比如git分支名、目录名、模型名等。推荐使github开源项目：claude-code-statusline-pro-aicodeditor，效果如下：

详见：github.com/HorizonWing…

七、总结

差生文具多，尽管我暂时还没有使用 CC 产出啥说得上来的东西，但是确实花了很多时间琢磨怎么让它用起来更顺手。一些不成熟的想法，希望可以给到大家启发。

参考：

1. www.ginonotes.com/posts/how-i…
2. www.cnblogs.com/knqiufan/p/…

往期回顾

1.AI编程能力边界探索：基于 Claude Code 的 Spec Coding 项目实战｜得物技术

2.搜索 C++ 引擎回归能力建设：从自测到工程化准出｜得物技术 

3.得物社区搜推公式融合调参框架-加乘树3.0实战

4.深入剖析Spark UI界面：参数与界面详解|得物技术

5.Sentinel Java客户端限流原理解析｜得物技术

文 /羊羽

关注得物技术，每周更新技术干货

要是觉得文章对你有帮助的话，欢迎评论转发点赞～

未经得物技术许可严禁转载，否则依法追究法律责任。

一、前言

10 天，2.5 万行代码，提效 36%。 基于 Claude Code 的 Spec Coding（规格驱动编码） 深度实战。通过 2,754 次工具调用，我们不仅完成了从 0 到 1 的前端项目搭建，更在“约束+示范+视觉”的三层规范体系下，摸清了 AI 编程的真实能力边界。本文将复盘这场实战，拆解如何用结构化工作流消除 AI 的不确定性，重构开发者的核心竞争力。

二、Spec Coding

什么是 Spec Coding 工作流

众所周知，Spec Coding（规格驱动编码）的核心思想是：在写代码之前，先写规格文档。通过 openspec 工具，每个功能变更都经历以下阶段：

Spec 工作流的实际价值

减少返工： 在 proposal 阶段明确为什么以及怎么做，避免实现完才发现方向不对。适合复杂功能： 对于需要跨多个文件多个层次的功能，tasks 分组让 AI 聚焦在当前步骤。可审计： 每个 Change 的完整决策链（proposal→design→specs→tasks）都留有记录，方便回溯。

三、项目是什么

一个标准企业级中后台搭建，包括表格、表单、卡片列表、数据看板等中后台常见核心功能，项目从零搭建到完成以下全部功能，全程使用 Claude Code 辅助开发。

四、数据概览

在这次使用Claude Code 做 Spec Coding的从0到1项目探索中，我们积累了一份完整的原始数据，以下所有数字均来自Claude Code对 109 个 .jsonl 会话文件的整体数据统计：

2,754 次工具调用的分布揭示了 AI 的"工作方式"， AI 自主完成的 738 次文件读取、550 次代码编辑、662 次终端命令执行，以及 208 次任务进度标记——几乎覆盖了一个研发日常工作的全部动作类型。

五、开发时间线：10 天的演进过程

阶段一：设计阶段

在动工之前，我们完成了产品方向的确认和 UI 设计稿、产品PRD的输出。过程主要使用 Cursor + 设计规范 Rules，直接从概念沟通到生成高保真 UI 稿（HTML文件），再生成标准的 PRD 需求描述，覆盖系统所有核心页面。这一阶段的产出是一套可直接用于开发对齐的视觉参考，也是后续 AI 生成代码时的重要上下文来源。

阶段二：项目搭建（2个工作日，20 条指令）

此阶段我们以问答式交互为主，聚焦于项目基础设施的搭建和简单需求的尝试。我们向 AI 提出架构问题，由 AI 给出方案，我们决策后执行。在这个过程中，AI 帮助我们熟悉技术栈、搭建项目结构、配置开发环境，并完成了第一个核心列表页面的开发，成功打通了前后端的数据链路。

阶段三：功能开发（4个工作日，89 条指令）

这是整个项目开发强度最高的阶段，我们引入了“规格驱动编码”（Spec Coding）的工作流，约 80% 的功能代码在此阶段完成。我们不再是简单地给 AI 下达指令，而是先与 AI 共同定义清晰的功能规格（Specification），然后 AI 基于这份“蓝图”自主进行编码。通过这种方式，我们高效地完成了包括授权管理、数据分析看板、文档树状结构等多个复杂功能的开发。

阶段四：细节打磨与生产部署（4个工作日，108 条指令）

最后阶段的工作重心转向功能迭代、系统重构和生产环境的部署排障。我们与 AI 一起，对已有功能进行了多轮优化，例如完善了核心业务流程、重构了侧边栏导航、修复了登录跳转逻辑等。同时，我们也对项目首页进行了深度的代码重构，解决了前期快速迭代中积累的技术债。最后，在部署阶段，我们遇到了复杂的构建问题，通过与 AI 的多轮分析和尝试，最终定位并解决了问题，成功将应用部署上线。

六、典型案例

案例一：AI 驱动产品设计

没有产品经理、没有 UI 设计师，一个工程师如何用 AI 独立完成从产品定义到高保真原型、再到研发文档的全流程。

背景：

传统意义上，从 0 到 1 开发一个企业级知识问答平台需要三个角色：产品经理（需求分析 + 用户路径 + PRD）、UI 设计师（交互稿 + 高保真设计稿）、工程师（编码实现）。这个项目设计过程中，通过让 AI 在不同阶段扮演不同角色，覆盖了全部三个职责。

让 AI 扮演产品经理：

在 Rules 中植入「首席产品专家」Persona 提示词，将 AI 从工程师的「急于执行」模式切换为产品经理的「先想清楚」模式，与 AI 聊清楚我们想干什么。

让 AI 扮演 UI 设计师：

在 Rules 中定义设计规范，通过对话式生成逐页产出高保真 HTML 文件，而不是源码：

让 AI 生成研发可读的 PRD：

基于产品经理角色，将 HTML 设计稿作为上下文，最后生成精确到组件行为级别的 PRD：

案例二：SDD 驱动前端功能研发

在已有系统上增量交付一个完整功能模块，SDD 如何保证「增量」功能快速开发，并系统性提升前后端联调效率。比如其中有个SSD需求开发「定时任务管理」完整模块，并且对接 6 个后端接口。这是 SDD 工作流第一次被完整运用于新功能模块开发，也是验证「SDD + MCP」前后端联调提效的关键场景。

页面功能开发： opsx:new 到 archive，人工指令 < 10 条，AI代码占比100%，交付完整任务管理模块（独立路由 + 完整 CRUD + 执行记录 + 检索结果）。

前后端联调： SDD + MCP 的联调路径：接口 URL → MCP直连文档 → 一次性获取字段、枚举、必填项 →  接口文件一次生成 → ****联调一次通过，6 个接口零联调返工。

研发效率： 同日额外交付了两个完整模块，3个独立完整模块，单日全部开发完成，按纯人工开发，当天人效提升3倍。

案例三：SDD 驱动系统重构

重构与新功能的根本差异：

新功能开发是「从无到有」：AI 可以大胆生成，错了删掉重来。重构是「在活体系统上动手术」：这种高风险对 AI 执行提出了截然不同的要求——不仅要知道改什么，更要知道不能改什么，以及按什么顺序改。 SDD 的价值正在于此：在动代码之前，把这三件事全部写清楚。

知识问答首页重构：

架构债务： 大量首页业务组件与公共组件混放、useChat 导出 20+ 方法（4 种无关职责混合）、ChatInterface 接收 17 个 props（参数3 层传递）。

执行TASKS： 9 组 34 个子任务，从「grep 确认组件当前归属」→「按新分层迁移」→「更新所有 import 路径」→「tsc 类型检查」→「冒烟验证」，每一步有明确输入和验收标准。

执行结果： 34个任务全部完成（含 4 个验证任务），AI 全程独立执行，人工干预 < 5 条指令。7个业务组件与公共组件完成解耦，useChat 拆为 3 个单职责 hook，ChatInterface 从 17 个 props 缩减至 6-8 个。

案例四：复杂问题排障

并不是所有编程相关的问题AI都可以解决，哪类工程问题从结构上超出了 AI 的能力边界？这里举一个遇到的场景。

其中有一天遇到一个测试环境构建失败的问题，结果过程约 4 小时，7 个会话、15+ 次方案尝试、59 条指令。整个项目单日指令最多的一天，也是 AI 独立解决能力最受限的一天。

这一天有一个值得注意的特征：AI 每次分析都是正确的——问题不在于 AI 的分析能力不足，而在于问题的结构性特征超出了 AI 的信息范围和反馈机制：

• 云服务器构建时发生，本地无法复现： 每次验证方案必须提交代码等待 CI（一轮约 10 分钟），AI 分析的是日志截图，无法感知「现在的 CI 环境还有哪些隐性配置」。

• 多根因互相掩盖，解决一层才暴露下一层： AI 每次分析都正确，但正确分析的只是当前暴露的那一层，问题全貌无法被单次分析覆盖。

• 隐性行为无文档，根因藏在依赖源码内部： Prisma postinstall 境外下载没有任何显式错误，引导AI 不得不深入阅读 node_modules 源码第 2319 行才能发现根因。这类「运行时行为藏在依赖内部、没有文档描述」的问题，超出了 AI 通过训练数据或当前上下文主动推断的范围。

最后确认的原因：

• .npmrc 历史副作用： 早期为跳过 @next/swc-darwin-arm64 在 Linux 下载而加入的 omit=optional，无意间也跳过了 @tailwindcss/oxide-linux-x64-gnu（Tailwind v4 的 native binding），postinstall 陷入循环等待
• Prisma v6 境外下载沉默卡死： AI 需要阅读 node_modules/@prisma/fetch-engine/dist/index.js 第 2319 行才能发现这个行为——postinstall 不报错、不超时，只是无限等待。
• pnpm 跨平台 lockfile 不一致： macOS arm64 生成的 lockfile 不含 Linux x64 的 native package；切回 npm 则 lockfile 被忽略，安装结果每次不同。

最终解法（4 小时探索后得出）：

• 锁定 tailwindcss@4.1.11，配置
• PRISMA_ENGINES_MIRROR=registry.npmmirror.com/-/binary/pr…
• 统一使用 pnpm，CI 命令同步更新，删除 .npmrc 中的 omit=optional。

七、代码规范落地：CLAUDE.md 和 Rules 的实际效果

规范体系设计思想：三层结构

本项目的规范体系是三个层次的协同约束， 每层解决不同的问题：

第一层：约束层（.claude/rules/）      ← 告诉 AI「禁止什么、必须怎样」
第二层：示范层（.claude/code-design/）← 告诉 AI「标准产出长什么样」
第三层：视觉层（.claude/ui-design/）  ← 告诉 AI「页面应该长什么样」

为什么需要三层？

只有「约束层」时，AI 知道规则但缺乏参考实现，容易在复杂场景下产生符合规则但不符合团队风格的代码。加入「示范层」和「视觉层」后，AI 可以直接对齐团队的标准产出，减少「虽然合法但不地道」的代码。

第一层：约束层（.claude/rules/）

7 个规范文件，分别约束不同维度：

.claude/rules/
├── ts.md          # TypeScript 规范（禁止 any、使用可选链等）
├── code-names.md  # 命名规范（kebab-case/camelCase/PascalCase）
├── comment.md     # 注释规范（JSDoc、@ai-context/@ai-rules 文件头）
├── lint.md        # 代码风格（单引号、文件末尾换行）
├── style.md       # 样式规范（Tailwind CSS、less 文件）
├── pages.md       # 页面目录结构规范（constants/services/hooks/components 分层）
└── service.md     # API 接口生成规范（fetch{Name}Api 命名、UniversalResp 泛型）

第二层：示范层（.claude/code-design/）

将项目常见场景预置完整的「标准模板代码」，AI 在生成新页面时可以直接参照，后续可以切换为skills：

.claude/code-design/
├── pro-table/          # 通用列表页模板（含搜索、分页、批量操作、行操作）
├── pro-form/           # 通用表单页模板（含创建/编辑双模式、字段验证）
├── editable-pro-table/ # 可编辑表格模板（含行内编辑、添加/保存/删除）
├── drawer/             # 抽屉组件模板（含标准打开/关闭逻辑）
├── compontent/         # 通用组件模板（含 README、Props 定义、使用示例）
└── utils/              # 工具函数模板

示范代码的作用不只是「看个格式」。以 pro-table 为例，当开发者让 AI「参考 .claude/code-design/pro-table 生成知识治理列表页」时，AI 直接继承了这套模式，一次就能生成符合团队风格的代码，无需多轮调整。

第三层：视觉层（.claude/ui-design/）

注意存放 HTML 设计稿，覆盖主要页面的视觉参考：

.claude/ui-design/
├── knowledge-spaces.html  # 知识空间列表页设计稿
├── search-strategy.html   # 检索配置页设计稿
├── space-detail.html      # 空间详情页设计稿
└── xxx设计稿

这些 HTML 文件可以直接在浏览器中打开预览，AI 也可以读取其中的结构和样式信息。实践中，提供 HTML 设计稿后，AI 生成的 UI 与设计意图的吻合度明显高于纯文字描述，尤其是布局结构、颜色方案、间距配置等细节。

规范约束的实际效果

正面效果（规范被遵循的案例）：

• 接口命名一致性： 所有接口函数均以 fetch{Name}Api 命名，类型以 I{Name}Req/Res 格式，整个项目 205 个文件保持高度一致。
• 目录分层被遵守： constants/、services/、hooks/、components/ 分层在每个新页面中都被正确创建。
• 代码模板被继承： CURD页面均参照了 pro-table 模板的 hooks 分离方式，代码结构高度一致。
• 使用可选链： 几乎所有数据访问都使用了 ?. 和 ??，有效避免运行时报错。

需要人工干预的案例：

• 2/24，AI 生成知识空间列表后，将所有代码写在单文件中，未按规范分层。通过一条追问后，AI 重构为正确结构。
• 2/27，AI 错误地使用了 .less 后缀，但项目实际配置使用 SCSS，在收到错误提示后立即修正。
• 出现 antd v5 废弃 API（destroyOnClose、dropdownStyle），AI 习惯于使用训练数据中更常见的旧 API，需要通过报警信息触发修正。

结论：

规范体系对 AI 的约束是有效的，但规范文件只是「约束」而非「能力」——只有「约束层」时，AI 知道不能做什么，但遇到复杂场景仍可能生成不够地道的代码；加入「示范层」和「视觉层」后，AI 有了对齐的锚点，输出质量和一致性明显提升。

八、MCP 工具：消除信息断层

在 AI 辅助前端开发中，有两类高频信息断层，在此项目中进行了接入：

接口文档断层： 接口文档在 API平台，AI 无法直接访问，只能靠用户手工复制字段，容易遗漏、版本不一致。需求文档断层： PRD、设计文档存在飞书云文档中，每次引用都需要用户打开→复制→粘贴到对话框，打断思路。

MCP 一：接口文档直连

通过该工具，AI 可以根据接口 URL 自动拉取完整接口文档——包括入参字段、出参结构、枚举值定义、必填项标注。累计被调用了 21 次，完成39个接口联调 ，覆盖了几乎所有接口的初次接入和更新迭代场景。服务端接口未生效之前，并且支持同步生成mock数据，减少后端依赖。interface.ts 类型定义质量非常高，字段注释完整，无需人工校对。

MCP 二：飞书云文档直读

通过该MCP工具，AI 可以直接读取飞书云文档的内容（PRD、设计说明、技术文档等），无需用户手工打开→复制→粘贴。

典型应用场景：

九、AI Spec Coding 经验总结

重新理解「AI 辅助编程」是什么

流行的说法是「AI 是你的 Copilot」。这个比喻在日常补全层面成立，但在 Spec Coding 实践之后，我更倾向于另一个模型：AI 是一个极度服从、无限耐心、但没有内部业务知识常识的「顶级执行者 」。

这个比喻捕捉了三个关键特征：

极度服从： AI 会一字不差地执行你写的规范，不会主动质疑「这样做合理吗」。这是优势，也是风险——规范写得越准确，执行越可靠；规范有歧义，AI 会选一个「看起来合理」的解释，而不是停下来问你。

无限耐心： 34 个任务的重构、9 组联调任务、跨会话的上下文恢复——这些在人类身上需要消耗大量意志力的事情，AI 做起来没有摩擦成本。本项目 208 次 TodoWrite 调用背后，是 AI 持续更新进度状态、从不嫌烦的特性。

没有内部业务常识： AI 不知道你们公司的部署环境是什么样的，不知道这个接口上周刚换过版本，不知道「这个交互做成这样用户会抱怨」。它只知道你告诉它的。这也是 3/4 生产构建排障花了大量时间的根本原因。

AI 的能力边界在哪里

从 10 天、2,754 次工具调用中，我们归纳出一个更精确的能力边界框架，而不是简单的「能做/不能做」：

真实项目中的并不是所有的需求都值得写一份 Spec。在真实的项目迭代中，我们需要根据需求颗粒度来选择协作模式。

小颗粒需求：对话框即扫即改

• 场景：改个文案、修个显隐逻辑、调整 CSS 间距。
• 策略：直接在 Cursor Chat  中对话。
• 理由：沟通成本低于编写规范的成本，AI 的即时反馈效率最高。

中颗粒标准化需求：基于Rules 或者 Skills 预设规范生成

• 场景：增加一个标准的 CRUD 页面、创建一个简单的业务组件。
• 策略：利用预设的 Cursor Rules 或 Skills（如 pro-table.mdc）。
• 理由：这类需求有强烈的“模式感”。只要规则定义清晰（如“执行流程：识别场景 -> 读取示例 -> 生成类型 -> 完成 UI”），AI 就能基于标准化模板高质量输出。

中大颗粒复杂功能：OpenSpec 深度协作

• 场景：重构核心逻辑、新增带有复杂业务逻辑的模块、无参考代码的新功能。
• 策略：OpenSpec 标准流 (SDD)。
• 理由：业务逻辑复杂时，AI 极易产生幻觉或需求偏移。通过 Spec 强制进行“先设计后编码”，可以确保 AI 的每一步都在既定轨道上，且 Spec 记录了设计的决策过程，对于后期维护价值巨大。

AI 失效的三种模式

经过本项目的实践，AI Coding 的失效不是随机的，而是可归类的：

模式一：规范真空

任务涉及的领域没有规范约束，AI 自行填充「合理默认值」。

• 表现：生成的代码功能正确，但风格/结构偏离团队约定。
• 发生频率：高（尤其在新功能开发初期）。
• 应对：在 CLAUDE.md 或 code-design 中补充对应规范，一次修复，全局生效。

模式二：信息孤岛

AI 掌握的信息是当前会话的快照，看不到系统外的状态。

• 表现：本地正常，CI 失败；AI 分析每次都对，但解的都是当前暴露的问题。
• 发生频率：低，但代价高。
• 应对：跨平台、跨环境的依赖要在架构设计阶段提前锁定；环境差异要写成规范前置处理。

模式三：任务目标模糊

AI 把「该问人的问题」当成「执行问题」来解决。

• 表现：用户说「优化一下首页」，AI 悄悄改了组件结构，而不是先澄清目标。
• 发生频率：中。
• 应对：Spec 工作流的 proposal 阶段强制要求先描述「Why」，避免 AI 自行填充目标。

开发者角色的重构

AI Coding 不是让开发者「消失」，而是让开发者的工作向上迁移：

这意味着：

规范设计能力成为 AI 时代开发者的核心竞争力——能写出让 AI 可靠执行的规范，价值比能写出同等功能代码更高。

系统性思维变得更重要——生产构建问题的排障经历说明，AI 可以帮你解决每一个局部问题，但无法帮你看到真实业务全局。

质量意识前移——过去 Code Review 在代码写完后进行，现在需要在 方案设计/任务执行 阶段就介入，而不是等 AI 执行完再纠错。

值得期待的方向

基于本项目的数据和经验，后续在以下方向可作深入探索：

规范体系的结构化积累： 每次踩坑后补充到 CLAUDE.md/rules，形成团队共享的「AI 执行约束库」。目前 7 条规范文件是手动维护的，下一步可以建立「踩坑→提炼规范→自动追加」的闭环。

MCP 工具链的纵向延伸： 本项目 MCP 仅覆盖了接口文档、飞书文档。后续针对设计稿、测试用例、发布平台、日志平台接入，可以进一步形成完整的AI Coding链路。

多 Agent 并行开发： 本项目开发过程中，发现大型任务执行等待时间较长，下一步可以尝试多Agen并发生成，同时开发不同功能模块。

一句话总结

AI Coding 的本质不仅仅是用 AI 写代码，而是用结构化的规范和工作流把不确定性消除在执行之前——AI 负责在确定性空间里高速执行，人负责维护和扩展那个确定性空间的边界。

10 天、217 条指令、2,754 次工具调用、25,546 行净增代码——这个数字背后，是一套让 AI 可以「看见」、「理解」、「遵守」团队约定的规范体系。规范是杠杆，AI 是力，Spec 工作流是支点。

本报告由claude code基于claude code 109 个真实历史会话、2,754 次工具调用记录生成，人工补充并校准，数据来源：~/.claude/projects/-Users-admin-Desktop-code-knowledge-qa/。

往期回顾

1.搜索 C++ 引擎回归能力建设：从自测到工程化准出｜得物技术

2.得物社区搜推公式融合调参框架-加乘树3.0实战 

3.深入剖析Spark UI界面：参数与界面详解|得物技术

4.Sentinel Java客户端限流原理解析｜得物技术

5.社区推荐重排技术：双阶段框架的实践与演进｜得物技术

文 /阳凯

关注得物技术，每周更新技术干货

要是觉得文章对你有帮助的话，欢迎评论转发点赞～

未经得物技术许可严禁转载，否则依法追究法律责任。

一、为什么要做这件事

在搜索系统中， C++ 引擎长期扮演着底层核心基础设施的角色：性能敏感、逻辑复杂、变更频繁，同时承载着大规模线上流量的稳定运行。随着业务持续发展和技术架构不断演进，我们逐步意识到：在高频迭代背景下，回归能力也需要同步升级。

过去一年，我们围绕搜索 C++ 引擎展开了一次系统性的回归能力工程化建设。本文将介绍这次能力升级的背景思考、核心设计思路以及落地实践。

高频迭代背景下：回归能力需要同步升级

搜索 C++ 引擎的升级主要来自三类需求：业务功能需求、重要技术项目（有 QA 深度参与）、大量技术优化与结构性改造需求。

在实际迭代节奏中，技术优化与结构性改造类需求占比较高，引擎整体呈现出多人并行开发、持续迭代推进的状态。随着规模扩大，我们发现：现有回归环境更适用于单次项目式验证。多需求并行时，资源调度与复用能力仍有提升空间，回归准出标准尚未完全工程化。这意味着，在稳定性要求不断提升的背景下，我们有必要构建更加标准化、流程化的回归体系，让质量保障能力与迭代节奏匹配。

现有测试方式的演进空间

当前搜索引擎主要依赖两类测试手段：DIFF 测试和压测，这些手段在长期实践中发挥了重要作用，但随着业务复杂度提升，我们也逐步看到进一步优化的空间：流量获取依赖下载日志、手工上传，自动化程度仍可提升。DIFF 过程中存在自然噪音。需要更精细化处理（AA DIFF、排序不稳定）。报告与分析信息分散在不同工具中，定位效率有优化空间。多套工具并行使用，缺乏统一平台化沉淀。整体来看，测试能力更多体现为“工具能力集合”，而在流程标准化、资产沉淀与统一治理方面仍有提升空间。

二、我们要解决什么问题

这次建设的目标，并不是简单“再做一个工具”，而是希望系统性解决以下问题：让 DIFF 和压测成为搜索 C++ 引擎的标配回归能力、让回归结果具备可分析、可归因能力、让回归成为发布的硬性准出标准、保证工具本身的稳定性，不成为新风险、整体提升引擎的回归效率和交付质量、通过流程和流水线，降低对“人”的依赖。一句话总结：把回归这件事，从“靠自觉”，变成“靠系统”。

三、整体方案概览

围绕上述目标，我们将建设拆分为五个关键方向：流量录制：一次录制，多处复用。环境建设：稳定、可复用的 DIFF/ 压测环境。DIFF 工具体系：从“能跑”到“好分析”。一键压测能力：降低执行门槛。工具与索引平台集成：让回归真正被用起来。

下面将会按模块展开说明。

流量录制：回归的基础设施

为什么先做流量录制

DIFF 和压测的核心前提只有一个：真实、稳定、可复用的流量。因此我们优先建设了搜索 C++ 引擎的流量录制链路，作为后续所有测试能力的基础。

流量如何触发

• 在索引平台集群详情页直接发起流量录制。
• 索引平台更新 ARK 配置中心中的录制配置。
• 搜索 C++ 引擎实时监听配置变化。

录制配置设计

所有配置统一收敛在 dsearch3#test.properties，支持：

• 全局开关。
• 指定 app / group。
• 截止时间。
• 指定 IP。
• 采样率（0～100）。

这使得录制行为可控、可回收、可精细化管理。

流量生成与存储

• 引擎侧根据配置生成 Kafka 消息。
• 多业务场景复用同一 ARK 集。
• 多场景流量复用同一个 Kafka Topic。

最终流量落入 ODPS，按天分区，字段包含：

• 请求体。
• 流量场景。
• 实验信息。
• 环境信息（生产 / 预发）。

这为后续 DIFF、压测、问题复现提供了统一数据源。

流量存储字段说明：

request_type:流量标签（原C++引擎请求类型）
app_name:C++引擎appName
group_name:C++引擎groupName
request_body:录制的C++引擎请求体
env:录制的流量环境：预发/生产
graph_name:图名称
experiments：实验列表（搜索新增）
pt:ODPS分区，按天分

DIFF 测试：从无到“可归因”

DIFF 执行流程：

DIFF 的入口统一在索引平台：查询流量 →选择流量→配置参数→触发 DIFF→查看报告。底层由测试服务 + 脚本完成：流量筛选与改造、请求转发、去噪、报告生成与存储。

DIFF 对比方式：

对照组部署 master 分支，实验组部署预发布分支。指定行或者指定集群方式请求对照组和实验组环境。打开新功能开关进行响应比对，生成预期有DIFF报告。

DIFF 环境设计

支持两种模式：

• 指定集群：对照组 / 实验组两套完整集群。
• 指定行 ： 精确绑定 search / rank IP。

通过该设计，保证对比的唯一变量只有代码和配置。

流量筛选与回放改造

支持多维度筛选：

• 搜索场景（交易 / 社区 / 聚合等）。
• 流量标签（综合 / 销量 / 新品等）。
• 实验命中情况。

同时解决了生产流量无法直接在预发回放的问题（表名、图参数、模型等适配）。

DIFF 策略设计

我们不只关注“有没有 DIFF ”，而是关注这个 DIFF 是否符合预期，因此 DIFF 被拆为两类：

响应 DIFF

• 响应字段对比。
• 漏斗算子字段对比。

指标 DIFF

• 相似度分布（忽略/不忽略排序）。
• 漏斗算子一致率。
• 字段增删改统计。
• 定制化指标。

DIFF 去噪

DIFF 不可用，往往不是因为“真问题”，而是噪音太多。我们重点处理了：AA DIFF（排序不稳定、非确定性逻辑）、可忽略字段、数值微小波动、内部超时导致的异常结果，目标只有一个：让开发看到的DIFF，尽可能都是真问题。

DIFF 报告设计

报告展示

DIFF 汇总报告：

• 应用、集群、请求接口、流量标签、路由信息、对比数量、DIFF 数量、完全一致率、query_tag 平均召回数、score 平均分等。
• 相似度分布统计报告（不忽略排序/忽略排序）。
• 漏斗算子一致率统计报告。
• 字段增删改统计。

DIFF 详情报告：

• traceId、一致率、增删改字段、请求体等。
• 漏斗算子 DIFF 明细。
• 响应 DIFF 明细。

报告通知

通知到群 @个人，添加报告链接。

压测：一键完成性能回归

压测执行流程：

• 索引平台作为压力测试发起入口，查询流量->选择流量->填写压测参数->压测触发->压测记录查看。
• 测试服务提供索引平台操作的接口能力，查询流量->流量筛选->压测文件生成->压测任务触发->压测状态更新。
• 压测平台提供实际压测能力，启动压测任务->生成压测报告。

整个过程无需人工干预。

执行方式：

• 对照组：master 分支。
• 实验组：预发布分支。
• 开启新功能开关。
• 阶梯式加压，对比性能曲线。

压测环境设计

同 DIFF 环境建设。

压测报告设计

报告展示

压测平台报告。

报告通知

通知到群 @个人，添加报告链接。

发布流水线与准出机制

回归能力建设的最终目标，是进入发布流程。当前已完成：UT / MR 流水线初步建设，后续规划中将：把 DIFF 和压测作为发布硬性卡点、回归不通过，禁止上线、回归过程自动扩缩容，避免长期占用资源、自动生成准出报告。

四、后续规划

回归执行率 100%：解决“忘跑回归”。

准出流水线全自动化。

横向覆盖更多搜索场景（流控、商业化、国际搜索等）。

形成统一的上线 SOP 规范。

五、总结

搜索 C++ 引擎回归能力建设，并不是一次“工具升级”，而是一场工程化治理：把经验变成流程、把自觉变成约束、把风险前移到上线之前，最终目标只有一个：让搜索引擎的每一次升级，都更可控、更可信。

往期回顾

1.得物社区搜推公式融合调参框架-加乘树3.0实战

2.深入剖析Spark UI界面：参数与界面详解|得物技术 

3.Sentinel Java客户端限流原理解析｜得物技术

4.社区推荐重排技术：双阶段框架的实践与演进｜得物技术

5.Flink ClickHouse Sink：生产级高可用写入方案｜得物技术

文 /耿辉

关注得物技术，每周更新技术干货

要是觉得文章对你有帮助的话，欢迎评论转发点赞～

未经得物技术许可严禁转载，否则依法追究法律责任。