得物用Spec驱动Claude Code完成项目开发

项目为一个标准企业级中后台（表格、表单、卡片列表、数据看板等），从零搭建到功能完成全程使用 Claude Code 辅助开发。团队采用 Spec Coding（规格驱动编码）：写代码前先写规格文档，借助 openspec 工具让每个功能变更经历 proposal→design→specs→tasks 阶段，以减少返工、支撑跨文件跨层次的复杂功能、并保留可审计的完整决策链。10 天演进分四阶段：设计阶段（用 Cursor + 设计规范 Rules 从概念沟通直接生成高保真 HTML 稿并产出标准 PRD）、项目搭建（2 个工作日、20 条指令，问答式交互完成基础设施与第一个列表页并打通前后端链路）、功能开发（4 个工作日、89 条指令，引入 Spec Coding，约 80% 功能代码在此完成，含授权管理、数据分析看板、文档树状结构）、细节打磨与生产部署（4 个工作日、108 条指令，含多轮优化、首页重构、构建排障并成功上线）。全部数字来自 Claude Code 对 109 个 .jsonl 会话文件的统计：2,754 次工具调用中 AI 自主完成 738 次文件读取、550 次代码编辑、662 次终端命令执行、208 次任务进度标记；合计 10 天、217 条指令、25,546 行净增代码，提效 36%。文中也记录了边界：某次测试环境构建失败排障耗时约 4 小时、跨 7 个会话、15+ 次方案尝试、59 条指令，根因为 .npmrc 历史 omit=optional 副作用、Prisma v6 境外下载沉默卡死、pnpm 跨平台 lockfile 不一致三类隐性行为叠加。 项目中两类高频信息断层通过 MCP 接入解决：其一是接口文档断层——接口文档在 API 平台，AI 无法直接访问，以往只能靠人工复制字段，易遗漏且版本不一致；接入接口文档 MCP 后，AI 可根据接口 URL 自动拉取完整接口文档（入参字段、出参结构、枚举值定义、必填项标注），累计被调用 21 次、完成 39 个接口联调，覆盖几乎所有接口的初次接入与更新迭代场景，服务端接口未生效前还支持同步生成 mock 数据以减少后端依赖，生成的 interface.ts 类型定义字段注释完整、无需人工校对。其二是需求文档断层——PRD 与设计文档存放在飞书云文档，以往每次引用都要打开、复制、粘贴；接入飞书云文档 MCP 后 AI 可直接读取。典型收益案例是「定时任务管理」模块：该模块对接 6 个后端接口，走“接口 URL → MCP 直连文档 → 一次性获取字段、枚举、必填项 → 接口文件一次生成 → 联调一次通过”，实现 6 个接口零联调返工；该模块从 opsx:new 到 archive 人工指令少于 10 条、AI 代码占比 100%，当日还额外交付两个完整模块，按纯人工口径当天人效提升 3 倍。 项目为约束 AI 输出建立三层协同规范：第一层约束层（.claude/rules/）含 7 个规范文件，分别约束 TypeScript（禁止 any、使用可选链）、命名（kebab-case/camelCase/PascalCase）、注释（JSDoc、@ai-context/@ai-rules 文件头）、代码风格（单引号、文件末尾换行）、样式（Tailwind CSS、less 文件）、页面目录结构（constants/services/hooks/components 分层）、API 接口生成（fetch{Name}Api 命名、UniversalResp 泛型）；第二层示范层（.claude/code-design/）预置 pro-table、pro-form、editable-pro-table、drawer、compontent、utils 等完整标准模板代码，供 AI 生成新页面时直接参照（后续可切为 skills）；第三层视觉层（.claude/ui-design/）存放可直接浏览器打开的 HTML 设计稿（如 knowledge-spaces.html、search-strategy.html、space-detail.html），使 AI 在布局结构、颜色方案、间距配置上的吻合度明显高于纯文字描述。效果上，全部接口函数均以 fetch{Name}Api 命名、类型以 I{Name}Req/Res 格式，项目 205 个文件保持高度一致，目录分层与 pro-table 模板的 hooks 分离方式在新页面中被稳定继承；文中也列出仍需人工干预的案例（2/24 单文件未分层经一条追问后重构、2/27 误用 .less 后缀、antd v5 废弃 API destroyOnClose/dropdownStyle 需靠报警触发修正）。