Claude Code项目实战：AI编程边界深度探索

一、前言

10天，2.5万行代码，整体效率提升36%——这些成果源自一次基于Claude Code的Spec Coding（规格驱动编码）深度实战。通过2,754次工具调用，我们从零起步搭建了一个完整的前端项目。在“约束+示范+视觉”三层规范体系下，我们切实摸清了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探索，积累了一套完整的原始数据。以下数字全部来自对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共同定义清晰的功能规格，然后让AI基于这份“蓝图”自主编码。授权管理、数据分析看板、文档树状结构这些复杂功能，都是通过这种方式完成的。

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

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

六、典型案例

案例一：AI驱动产品设计

在没有产品经理和UI设计师的情况下，一个工程师如何依靠AI独立完成从产品定义到高保真原型，再到研发文档的全流程？

背景：

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

让AI扮演产品经理：

在Rules中植入“首席产品专家”的角色提示词，将AI从“急于执行”的工程师模式切换到“先想清楚”的产品经理模式，先与AI沟通清楚到底要做什么。

让AI扮演UI设计师：

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

让AI生成研发可读的PRD：

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

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

在已有系统上增量交付一个完整的功能模块，SDD如何既保证“增量”功能快速开发，又系统性提升前后端联调效率？以“定时任务管理”完整模块为例，需要对接6个后端接口。这是SDD工作流首次被完整运用于新功能模块开发，也是验证“SDD + MCP”前后端联调提效的关键场景。

页面功能开发：从opsx:new到archive，人工指令不足10条，AI代码占比100%，交付了完整的任务管理模块——独立路由、完整CRUD、执行记录、检索结果，一应俱全。

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

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

案例三：SDD驱动系统重构

重构与新功能的本质差异在哪里？

新功能开发是“从无到有”，AI可以大胆生成，错了删掉重来。但重构不同——这是在活体系统上动手术，风险更高。不仅要明确改什么，更要清楚不能改什么，以及按什么顺序改。SDD的价值就在这里：动代码之前，先把这三件事全部写清楚。

知识问答首页重构：

架构债务：大量首页业务组件与公共组件混放；useChat导出了20多个方法，4种无关职责混在一起；ChatInterface接收了17个props，参数需要经过3层传递。

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

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

案例四：复杂问题排障

并非所有编程问题AI都能解决。那类工程问题，从结构上就超出了AI的能力边界？这里有一个典型的例子。

某天遇到了测试环境构建失败的问题，整个过程耗时约4小时，涉及7个会话、15次以上的方案尝试、59条指令。这是整个项目单日指令最多的一天，也是AI独立解决能力最受限的一天。

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

• 云服务器构建时发生，本地无法复现：每次验证方案都得提交代码等CI跑一轮（大约10分钟），AI分析的是日志截图，但无法感知“当前的CI环境还有哪些隐性配置”。
• 多个根因互相掩盖，解决一层才暴露下一层：AI每次分析都对，但对的只是当前暴露出来的那一层，问题全貌无法被单次分析完全覆盖。
• 隐性行为没有文档，根因藏在依赖源码深处：Prisma的postinstall在境外下载时没有显式错误，必须深入阅读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=https://registry.npmmirror.com/-/binary/prisma。
• 统一使用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在生成新页面时可以直接参考：

.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/分层在每个新页面中都被正确创建。
• 代码模板被继承：几乎所有CRUD页面都参照了pro-table模板的hooks分离方式，代码结构高度一致。
• 使用可选链：几乎所有数据访问都使用了?.和??，有效避免了运行时报错。

需要人工干预的案例：

• 有一次，AI生成知识空间列表后，将所有代码写在一个单文件里，没有按规范分层。不过追问了一句后，AI就重构成了正确结构。
• 还有一次，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不知道你们公司的部署环境是什么样，不知道这个接口上周刚换过版本，不知道“这个交互做成这样用户会抱怨”。它只知道你告诉它的。这也是那4小时生产构建排障花费大量时间的根本原因。

AI的能力边界在哪里

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

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

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

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

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

• 场景：增加一个标准的CRUD页面、创建一个简单的业务组件。
• 策略：利用预设的Cursor Rules或Skills（比如pro-table.mdc）。
• 理由：这类需求有强烈的“模式感”。只要规则定义清晰，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并行开发：本项目开发过程中发现，大的任务执行等待时间较长。下一步可以尝试多Agent同时生成，同时开发不同的功能模块。

一句话总结

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

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

本报告由Claude Code基于109个真实历史会话、2,754次工具调用记录生成，人工补充并校准。