AI 提效工程化深度实践

工程基座：CLAUDE.md + Hooks —— AI 研发体系

核心定位：作为整个 AI 提效体系的底层基座，给 AI 明确项目的"游戏规则"，同时通过自动化 Hooks 实现全流程质量兜底，解决 AI 产出不符合项目规范、风险操作不可控的核心痛点。

中高级进阶落地实践：

• 搭建了三级 CLAUDE.md 体系，实现 AI 上下文的全场景覆盖：
  • a. 全局级 ~/.claude/CLAUDE.md ：定义个人/团队通用编码规范、AI 交互规则、语言偏好、安全红线；
  • b. 项目级 项目根目录/CLAUDE.md ：明确项目技术栈、架构分层、目录结构、编码规范、常用命令、权限规则，是 AI 理解项目的核心入口；
  • c. 模块级 src/xxx/CLAUDE.md ：针对特定模块（如组件库、权限系统）的特殊规则、实现约定、复用规范，实现精细化的 AI 上下文控制。

项目级 CLAUDE.md 完整落地代码：

# 企业 SaaS 管理系统 - AI 开发说明书

## 技术栈

- 框架: Next.js 14 (App Router)
- 语言: TypeScript 5.3 (strict mode)
- 样式: Tailwind CSS 3.4 + shadcn/ui
- 状态管理: Zustand
- 数据获取: SWR
- 测试: Vitest + React Testing Library

## 项目结构

src/
├── app/ # Next.js App Router 路由页面
├── components/ # 可复用公共组件（按业务模块拆分）
├── hooks/ # 自定义 React Hooks
├── lib/ # 工具函数、常量定义、类型统一定义
├── services/ # API 调用层、请求封装
└── types/ # 全局 TypeScript 类型声明

## 编码规范

- 组件: 函数式组件 + React Hooks，禁止 class 组件
- 命名: 组件 PascalCase，工具函数 camelCase，常量 UPPER_SNAKE_CASE
- 类型: 禁止使用 any/unknown，必须定义完整 Props Interface
- 导入: 统一使用@/ 路径别名，禁止相对路径跨多层级导入
- 错误处理: 所有异步操作必须有完整 try/catch，前端友好错误提示

## 常用命令

- 开发启动: pnpm dev
- 生产构建: pnpm build
- 单元测试: pnpm test
- 代码规范检查: pnpm lint
- 代码格式化: pnpm format

• 引导文案：配套 Hooks 自动化触发器，实现 AI 操作的全流程质量管控与风险拦截，在 .claude/settings.json 中完成完整配置：

Hooks 完整落地配置代码：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $CLAUDE_FILE_PATH"
          },
          {
            "type": "command",
            "command": "npx eslint --fix $CLAUDE_FILE_PATH"
          },
          {
            "type": "command",
            "command": "npx tsc --noEmit $CLAUDE_FILE_PATH"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c '[[ \"$CLAUDE_FILE_PATH\" == *.env* ]] && echo BLOCK || exit 0'"
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "idle_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Ping.aiff"
          }
        ]
      }
    ]
  }
}

• 核心能力：PostToolUse Hook 在 AI 编辑代码后自动执行格式化、规范修复、类型校验，确保代码 100%符合规范；PreToolUse Hook 拦截.env 等敏感文件修改，避免安全风险；Notification Hook 实现任务完成自动通知。

• 提效价值：项目规范对齐成本降低 100%，AI 产出的代码规范符合度从 60%提升至 100%，高危操作拦截率 100%，从源头解决了 AI 代码的质量与安全问题。

需求定义：Spec —— 让 AI 准确理解需求

• 核心定位：解决 AI 需求传递损耗、反复返工、产出不符合预期的核心痛点，核心理念是「AI 不怕需求长，怕需求不清晰」，是 AI 提效的第一个核心杠杆点。

• 中高级进阶落地实践：

  • 搭建了团队标准化的 Spec 模板体系，覆盖功能开发、组件封装、工具脚本、Bug 修复等全研发场景，每个 Spec 严格包含：目标描述、技术约束、功能需求、边界条件、验收标准 5 大核心模块，无歧义、可执行、可验收；
  • 将 Spec 与团队研发流程深度结合，需求评审后直接输出标准化 Spec，作为 AI 开发的唯一输入，同时和后续的 Skill 能力联动，通过 /feat Skill 直接读取 Spec 自动执行全流程开发。

团队通用 Spec 完整落地模板（以用户登录模块为例）：

# Feature: 用户登录模块

## 目标描述

实现基于 JWT 的用户登录功能，支持邮箱密码登录和 Google OAuth 第三方登录，满足 SaaS 系统用户身份认证核心需求。

## 技术约束

- 框架: Next.js 14 App Router
- 状态管理: Zustand
- UI 组件: shadcn/ui
- 接口规范: RESTful API，路径前缀 /api/v1
- 安全规范: 密码加密传输、CSRF 防护、httpOnly Cookie 存储

## 功能需求

1. 邮箱 + 密码登录表单，包含邮箱、密码输入框、记住我选项、登录按钮
2. Google OAuth 登录按钮，一键跳转授权流程
3. 登录状态持久化，通过 httpOnly Cookie 存储 Token，7 天免登录
4. 登录失败错误提示，精准区分账号不存在、密码错误、网络超时、限流拦截场景
5. 表单客户端实时校验，提交前拦截非法输入

## 验收标准

- [ ] 登录成功后自动跳转至 /dashboard 首页
- [ ] Token 过期自动触发无感刷新，不中断用户操作
- [ ] 密码输入框支持显示/隐藏切换，移动端适配密码键盘
- [ ] 邮箱格式、密码最少 8 位强校验，实时反馈校验结果
- [ ] 登录 API 请求响应时间 < 500ms，超时自动重试 1 次
- [ ] 适配移动端、PC 端全尺寸屏幕，操作按钮最小触摸目标 44px

## 边界条件

- 不包含: 用户注册、密码找回、账号注销功能
- 错误处理: 网络超时展示重试按钮，服务端 500 错误展示通用友好提示
- 安全: 密码全程不明文传输、不明文存储，防 XSS 注入，自动携带 CSRF Token

提效价值：需求返工率从 40%降低至 5%以内，AI 产出的需求符合度从 30%提升至 95%以上，单次需求沟通成本降低 90%。

视觉规范：DESIGN.md —— 让 AI 产出一致 UI 设计系统

• 核心定位：前端专属提效模块，解决 AI 生成 UI 样式混乱、不符合设计规范、反复调像素的核心痛点，是前端工程师 AI 提效的核心差异化竞争力。

• 中高级进阶落地实践：

  • 基于 Google Stitch 标准，搭建了团队级的 DESIGN.md 设计系统，统一定义了 9 大核心章节：视觉主题与氛围、语义化颜色系统、字体层级规则、组件样式规范、布局原则、阴影层级、设计护栏、响应式规则、Agent 提示指南；
  • 将 DESIGN.md 与团队组件库、设计规范深度绑定，同时通过 MCP 协议对接 Figma，自动同步设计令牌更新 DESIGN.md，确保 AI 生成的 UI 与设计系统 100%一致。

快速开发：Vibe Coding —— 上下文质量决定 10 倍开发速度上限

核心定位：基于完整的基座与规范，实现生产级的快速开发，区别于初中级"无脑让 AI 写代码"的表层应用，核心理念是「你掌控全局，AI 处理实现细节」。

中高级进阶落地实践：

• 建立了精准上下文 Vibe Coding 标准指令范式，所有指令必须包含：技术栈约束、架构要求、规范标准、边界条件、验收标准 5 大核心要素，彻底告别模糊指令。

Vibe Coding 指令对比落地代码：

❌ 初中级低质指令：
"帮我做一个用户管理表格组件"

✅ 中高级精准指令：
"基于shadcn/ui的DataTable组件实现一个用户管理表格，
要求支持服务端分页、列排序、行选择、批量删除/禁用操作。
使用TanStack Table v8的columnDef标准模式开发，
数据通过SWR从 /api/v1/users 接口获取，
表格分页、筛选、排序状态持久化到URL searchParams中，
严格遵循项目根目录DESIGN.md设计规范，
使用TypeScript严格模式，禁止any类型，
包含完整的加载态、错误态、空数据态处理。"

• 形成了多轮迭代的 Vibe Coding 开发流程：基于 Spec 和 DESIGN.md 生成核心架构 → 拆分模块分步实现 → 每步迭代做代码审查 → 自动跑测试验证 → 最终合并，全程只需要通过自然语言驱动迭代，无需手动修改代码；
• 明确了 Vibe Coding 的适用边界：CRUD 页面、通用组件、工具脚本等标准化场景全面使用，核心算法、安全敏感逻辑、性能关键路径人工把控，平衡效率与风险。

Vibe Coding 核心逻辑对比：

传统编码：	想 → 逐行写代码 → 调试 → 优化 → 验收	（开发者控制每一行代码）
Vibe Coding：	描述意图与约束 → AI 生成代码 → 审查 → 迭代	（开发者掌控全局架构）

提效价值：标准化业务模块开发效率提升 10 倍，重复代码编写工作量降低 80%以上，开发者可以把 80%的精力投入到核心业务逻辑与架构设计中，而非重复的编码工作。

提效体系落地量化成果

这套 6 大模块闭环体系在 10 人前端团队落地后，取得了明确的业务成果：

• 团队整体需求交付周期从平均 5 个工作日缩短至 2 个工作日，研发效率提升 150%；
• 代码规范符合度从 72% 提升至 100%，线上 UI 还原度问题归零，线上 bug 率降低 58%；
• 新成员项目上手周期从 2 周缩短至 3 天，团队最佳实践复用率 100%；
• 开发者非核心编码工作量占比从 70% 降低至 20%，可以把更多精力投入到架构优化、核心业务攻坚与技术创新中。