1. 项目概述当AI成为你的编程副驾最近半年我身边几乎所有的一线开发者和技术Leader都在讨论同一个话题如何用好AI编程助手。从最初的惊喜、尝试到现在的深度集成与流程再造大家逐渐意识到单纯把AI当作一个更聪明的代码补全工具实在是暴殄天物。我们真正需要的是一个能理解业务、遵循规范、并可靠交付的“AI副驾驶”。这正是“AI规范驱动编程”这个项目诞生的背景。“AI规范驱动编程-harness工程项目实战”这个标题听起来有点拗口但拆解开来就非常清晰了。它的核心目标是构建一套工程化的方法Harness将AI编程如ChatGPT、Claude、GitHub Copilot等无缝、可控地融入到我们现有的软件开发流程中。这不仅仅是写几个提示词Prompt那么简单而是要解决一系列工程难题如何让AI生成的代码符合团队的编码规范如何确保它理解我们项目的特定架构和业务上下文如何将AI的产出纳入CI/CD流水线进行自动化验证以及如何衡量和提升AI辅助编程的整体效率与代码质量这个项目适合所有正在或计划规模化使用AI辅助编程的团队无论是前端、后端还是全栈开发者。如果你已经厌倦了在AI生成的代码上反复进行格式调整、依赖修复和逻辑纠错那么这套“规范驱动”的工程化实践或许能为你打开一扇新的大门。接下来我将结合一个真实的微服务项目实战从头到尾拆解我们是如何设计并落地这套体系的。2. 核心设计思路从“聊天式编程”到“工程化流水线”在项目初期我们团队也经历了典型的“聊天式编程”阶段打开一个聊天窗口描述需求复制粘贴代码然后花大量时间调试和适配。这种模式的问题很快暴露出来上下文丢失严重、代码风格混乱、对项目特有库和模式不熟悉、生成结果不可复现。我们意识到必须为AI建立一个稳定、可预测的“工作环境”。2.1 设计原则与架构选型我们的核心设计原则可以总结为三点上下文富化、流程自动化和质量门禁化。上下文富化AI模型就像一个新加入团队的实习生它对项目一无所知。我们的任务就是为它准备一份详尽的“入职手册”。这包括项目的技术栈说明、目录结构规范、编码风格指南ESLint/Prettier配置、核心业务领域的术语表、以及常用工具函数和组件的使用示例。我们不再期望通过一个冗长的Prompt来传递所有信息而是将这些上下文结构化、持久化。流程自动化将AI调用嵌入到开发者的自然工作流中而不是让他们切换工具。我们选择了与IDE如VS Code深度集成并与版本控制系统Git和CI/CD工具如Jenkins/GitHub Actions联动。目标是实现“需求输入-代码生成-初步验证-提交就绪”的半自动化流水线。质量门禁化AI生成的代码不能直接进入代码库。必须经过一系列自动化的质量门禁包括静态代码检查、单元测试、集成测试甚至安全扫描。只有通过的代码才能被推荐给开发者或者在某些严格约束的场景下自动提交。基于这些原则我们设计了以“Harness”套件/装备为核心的架构。这个Harness不是一个独立的软件而是一套配置、脚本和约定的集合主要包括上下文知识库一个专门维护的目录如.ai/context存放项目架构图、API文档片段、DTO定义、错误码枚举等。规范化Prompt模板针对不同任务如“生成CRUD接口”、“修复空指针异常”、“编写单元测试”的标准化Prompt其中包含变量占位符用于动态注入具体参数。本地验证脚本在代码生成后立即运行的轻量级检查脚本快速反馈格式、导入等低级错误。CI/CD集成插件在代码审查Pull Request环节自动触发AI辅助分析例如检查提交信息规范性、评估代码变更复杂度、甚至建议重构方案。2.2 工具链选型与考量市面上AI编码工具很多我们的选型策略是“主辅结合优势互补”。主力模型GitHub Copilot Claude 3 SonnetGitHub Copilot作为IDE的内嵌伴侣用于实时的行级或函数级补全、注释生成代码、以及简单的代码解释。它的优势是延迟极低与编写过程无缝融合。我们通过配置.github/copilot-instructions.md文件来为其提供项目级指令这是实现“规范驱动”的第一步。Claude 3 Sonnet用于处理更复杂的任务如生成一个完整的服务模块、进行代码重构设计、或者编写技术文档。选择Claude是因为其在长上下文、逻辑推理和对指令的遵循程度上表现非常出色特别适合我们定义的规范化Prompt模板。我们通过其API进行集成。辅助工具Cursor IDE虽然VS Code Copilot是主流但我们发现Cursor在基于AI的代码编辑体验上更为激进和流畅。它的“Chat with Workspace”功能能直接分析整个项目对于理解复杂上下文非常有帮助。我们在一些探索性任务或旧代码重构时会切换到Cursor。质量守卫静态分析工具链这是无论是否使用AI都必备的但在AI规范驱动中尤为重要。我们强化了ESLint规则集包含eslint-plugin-promise,eslint-plugin-import、Prettier、SonarQube以及单元测试覆盖率Jest/Istanbul的检查。关键点在于将这些工具的配置和规则也作为“上下文”的一部分暴露给AI例如在Prompt中明确写出“请遵循项目中的.eslintrc.js规则”。实操心得模型不是越新越好我们尝试过最新的GPT-4 Turbo和Claude 3 Opus。虽然它们在极限能力上更强但对于日常编码任务Sonnet和GPT-4的性价比和速度更优。更重要的是模型的稳定性比峰值能力更重要。频繁切换模型会导致Prompt工程需要不断调整反而降低效率。我们最终固定了工具链并针对其特性优化我们的Harness。3. 构建你的AI编程Harness从零到一理论说再多不如动手做。下面我就以一个新启动的Node.js后端微服务项目为例展示如何一步步搭建这个AI编程Harness。3.1 第一步初始化项目与上下文知识库创建项目后第一件事不是写代码而是创建AI的“入职包”。# 项目根目录 mkdir -p .ai/context mkdir -p .ai/prompts在.ai/context目录下我们创建了几个核心文件project-guide.md项目总览。# 项目指南用户订单中心服务 (Order-Center-Service) ## 技术栈 - 运行时: Node.js 18 - 框架: NestJS - 数据库: PostgreSQL (主数据), Redis (缓存) - ORM: TypeORM - 通信: RESTful API (内部), gRPC (预留) - 代码风格: Airbnb JavaScript Style Guide 变体 ## 核心业务概念 - **订单 (Order)**: 用户购买商品后创建状态包括 PENDING, PAID, SHIPPED, COMPLETED, CANCELLED。 - **订单项 (OrderItem)**: 订单内的具体商品条目包含商品ID、单价、数量。 - **用户 (User)**: 来自用户服务 (User-Service) 的引用本地只存储userId。 ## 架构约束 - 所有数据库操作必须通过 Repository 模式。 - 服务层 (Service) 负责业务逻辑控制器 (Controller) 只处理HTTP请求/响应。 - 对外暴露的DTO必须以 *.request.ts 和 *.response.ts 命名。 - 错误处理使用内置的 HttpException 和自定义的 BusinessException。api-conventions.mdAPI设计规范。# API 设计规范 - 路径格式: /api/v1/resource 或 /api/v1/resource/{id}/sub-resource - 方法语义: - GET: 查询不产生副作用。 - POST: 创建新资源。 - PUT: 全量更新资源。 - PATCH: 部分更新资源。 - DELETE: 删除资源。 - 响应格式: typescript interface ApiResponseT { code: number; // 业务码0为成功 message: string; // 提示信息 data: T; // 成功时返回的数据 timestamp: number; // 服务器时间戳 } common-errors.md常见错误与处理方式。example-component.md一个完整的模块示例包含Controller、Service、Entity、DTO和单元测试。3.2 第二步设计规范化Prompt模板在.ai/prompts目录下我们创建针对不同任务的Prompt模板。这是Harness的核心。generate-crud-service.prompt.md你是一个资深的Node.js/NestJS后端工程师。请根据以下上下文和指令生成符合项目规范的代码。 ## 项目上下文 {{project_context}} !-- 此处将由脚本自动注入 project-guide.md 的内容 -- {{api_conventions}} !-- 此处将由脚本自动注入 api-conventions.md 的内容 -- ## 当前任务 我们需要为资源 {{ResourceName}} 创建一组完整的CRUD API。 - 资源描述: {{ResourceDescription}} - 核心字段: {{ResourceFields}} (例如: id: string, name: string, status: ACTIVE|INACTIVE) ## 生成要求 1. **文件结构**请在当前目录下生成以下文件 - src/{{resource-name}}/entities/{{resource-name}}.entity.ts (TypeORM实体) - src/{{resource-name}}/dto/create-{{resource-name}}.request.ts (创建请求DTO) - src/{{resource-name}}/dto/update-{{resource-name}}.request.ts (更新请求DTO) - src/{{resource-name}}/dto/{{resource-name}}.response.ts (响应DTO) - src/{{resource-name}}/{{resource-name}}.service.ts (服务类) - src/{{resource-name}}/{{resource-name}}.controller.ts (控制器类) - src/{{resource-name}}/{{resource-name}}.module.ts (模块类) 2. **代码规范** - 严格遵循项目中的 .eslintrc.js 和 .prettierrc 配置。 - 实体类使用TypeORM装饰器并包含createdAt和updatedAt时间戳字段。 - DTO类使用class-validator装饰器进行输入验证。 - Service层包含完整的业务逻辑和错误处理。 - Controller层方法需添加Swagger装饰器 (ApiTags, ApiOperation等)。 3. **额外任务**在Service类中请为每个公共方法生成对应的Jest单元测试骨架describe和it块包含基本的成功用例。 请开始生成代码并确保代码可以直接运行。这个模板的关键在于{{}}占位符。我们会编写一个简单的Node.js脚本或使用Shell脚本在调用AI API前将这些占位符替换为具体的值并将相关的上下文文件内容注入进去。3.3 第三步开发本地脚手架与验证脚本为了让这个过程更流畅我们开发了一个简单的命令行工具ai-harness-cli可以用npm link全局安装。# 安装依赖 npm install -g commander axios inquirer一个简化的核心脚本示例 (cli.js)#!/usr/bin/env node const fs require(fs).promises; const path require(path); const { program } require(commander); const inquirer require(inquirer); const { callClaudeAPI } require(./api-client); // 封装了调用Claude API的函数 program .command(generate:crud) .description(通过AI生成符合规范的CRUD模块) .action(async () { // 1. 交互式收集参数 const answers await inquirer.prompt([ { name: resourceName, message: 请输入资源名英文如 product: }, { name: resourceDescription, message: 请描述该资源: }, { name: resourceFields, message: 请输入核心字段格式: name:string, status:ACTIVE|INACTIVE: }, ]); // 2. 加载上下文和模板 const projectContext await fs.readFile(path.join(__dirname, ../.ai/context/project-guide.md), utf-8); const apiConventions await fs.readFile(path.join(__dirname, ../.ai/context/api-conventions.md), utf-8); let promptTemplate await fs.readFile(path.join(__dirname, ../.ai/prompts/generate-crud-service.prompt.md), utf-8); // 3. 替换模板变量 promptTemplate promptTemplate .replace({{project_context}}, projectContext) .replace({{api_conventions}}, apiConventions) .replace(/{{ResourceName}}/g, answers.resourceName) .replace(/{{resource-name}}/g, answers.resourceName.toLowerCase()) .replace({{ResourceDescription}}, answers.resourceDescription) .replace({{ResourceFields}}, answers.resourceFields); console.log(正在调用AI生成代码...); // 4. 调用AI API const generatedCode await callClaudeAPI(promptTemplate); // 5. 解析AI返回的代码块并写入对应文件 await parseAndWriteFiles(generatedCode, answers.resourceName.toLowerCase()); // 6. 运行初步验证 console.log(运行初步代码检查...); const { execSync } require(child_process); try { execSync(npm run lint:fix, { stdio: inherit }); execSync(npm test -- src/${answers.resourceName.toLowerCase()}/*.spec.ts --passWithNoTests, { stdio: inherit }); console.log(✅ 代码生成并通过初步检查); } catch (error) { console.error(⚠️ 生成完成但初步检查未通过请手动修复。); } }); program.parse(process.argv);这个CLI工具完成了从收集需求、组装Prompt、调用AI到生成文件、运行初步检查的整个闭环。开发者只需要输入资源名和字段就能获得一个基本可用的、符合规范的CRUD模块骨架。4. 集成到CI/CD让AI成为质量守门员生成了代码只是第一步如何确保AI在整个开发周期中都发挥作用我们将其集成到了GitHub Actions工作流中。4.1 PR描述自动审查与增强我们在.github/workflows下创建了一个ai-pr-review.yml的工作流当有新的Pull Request时触发。name: AI PR 助手 on: pull_request: types: [opened, synchronize] jobs: analyze-pr: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: 分析PR变更 id: diff-analysis run: | # 获取PR的变更描述和文件列表 PR_BODY${{ github.event.pull_request.body }} CHANGED_FILES$(git diff --name-only ${{ github.event.pull_request.base.sha }} ${{ github.event.pull_request.head.sha }} | tr \n ,) echo pr_bodyEOF $GITHUB_OUTPUT echo $PR_BODY $GITHUB_OUTPUT echo EOF $GITHUB_OUTPUT echo changed_files$CHANGED_FILES $GITHUB_OUTPUT - name: 调用AI生成PR审查意见 uses: actions/github-scriptv6 with: script: | const { callAIAnalysis } require(./.github/scripts/ai-pr-analyzer); const prBody ${{ steps.diff-analysis.outputs.pr_body }}; const changedFiles ${{ steps.diff-analysis.outputs.changed_files }}.split(,); const analysis await callAIAnalysis(prBody, changedFiles); // 将分析结果以评论形式添加到PR github.rest.issues.createComment({ issue_number: context.issue.number, owner: context.repo.owner, repo: context.repo.repo, body: ## AI PR 分析报告\n${analysis} });配套的ai-pr-analyzer.js脚本会做以下几件事评估PR描述质量检查描述是否清晰是否关联了任务ID是否说明了变更原因和测试情况。如果不达标AI会建议改进描述。分析代码变更复杂度针对修改的文件AI会判断本次变更是否过于复杂例如一个提交里同时改了数据库实体、服务逻辑和API接口如果过于复杂会建议拆分成多个更小的、聚焦的PR。识别潜在风险基于变更内容AI会提示可能的风险点例如“你修改了UserService的create方法但相关的UserRepository测试文件user.service.spec.ts并未被修改请补充测试用例。”4.2 自动化代码改进建议在另一个工作流中我们集成了类似于SonarQube或CodeRabbit的AI代码审查工具。但更进一步我们配置了AI在发现某些特定类型问题时可以直接生成修复建议的代码片段Diff。例如当AI检测到一段代码违反了“单一职责原则”函数过长时它不会只是评论“这个函数太长了”而是会生成一个具体的重构建议// AI 生成的建议 Diff - async processOrder(orderId: string) { - // ... 50行混合了验证、计算、保存、发送通知的代码 ... async processOrder(orderId: string) { const order await this.validateOrder(orderId); const calculatedOrder await this.calculateOrderDetails(order); await this.persistOrder(calculatedOrder); await this.notifyRelatedSystems(calculatedOrder); return calculatedOrder; } private async validateOrder(orderId: string) { /* ... */ } private async calculateOrderDetails(order: Order) { /* ... */ } // ... 其他拆分出来的私有方法开发者可以非常直观地看到应该如何改进并一键应用这个Diff。5. 实战中的挑战与解决方案在推行这套Harness的过程中我们遇到了不少坑也积累了一些关键经验。5.1 挑战一AI的“创造性”与“规范性”冲突AI有时会“过度发挥”引入一些项目中没有使用但技术上很酷的库或设计模式。例如它可能突然在一个简单的服务里引入RxJS进行响应式编程。我们的解决方案 在Prompt模板中明确加入技术栈约束清单和禁止模式清单。## 技术栈约束 - **必须使用**NestJS, TypeORM, class-validator, Jest。 - **禁止使用**RxJS除非明确要求任何未被 package.json 记录的第三方库。 - **模式选择**优先使用Repository模式进行数据访问。禁止使用Active Record模式。同时在本地验证脚本中增加一个依赖检查步骤使用npm list或分析import语句确保生成的代码没有引入非法依赖。5.2 挑战二上下文长度与精度问题随着项目变大上下文文件如project-guide.md会越来越长。将全部上下文塞入每次Prompt不仅成本高而且可能导致模型忽略最新的、最相关的指令。我们的解决方案实现动态上下文加载。 我们不再总是加载全部上下文而是让CLI工具根据任务类型智能选择。当任务是“生成数据库实体”时只加载project-guide.md中的数据库约定部分和example-component.md中的实体例子。当任务是“编写业务逻辑”时则加载业务概念、错误处理以及相关的服务类示例。 我们通过简单的关键词匹配和章节提取来实现这一点这显著提升了AI响应的相关性和准确性。5.3 挑战三生成代码的“可测试性”不足AI生成的单元测试骨架常常是“Happy Path”测试边界条件和异常场景覆盖不足。我们的解决方案强化Prompt中对测试的要求。 我们修改了Prompt模板明确要求为每个主要方法生成至少三个测试用例成功路径测试输入合法参数验证预期输出。边界条件测试输入边界值如空字符串、最大值、最小值。异常路径测试输入非法参数验证是否抛出了正确的异常或返回了错误码。 此外我们还将项目的测试覆盖率要求如“分支覆盖率80%”写在上下文中不断提醒AI。5.4 挑战四团队习惯与接受度不是所有工程师都愿意改变习惯。有些人觉得学习这套Harness的成本高于其收益。我们的解决方案渐进式推广先在技术债重、模式固定的CRUD模块生成上推广让团队成员看到其节省的巨量重复劳动。提供“安全网”强调所有AI生成的代码都必须经过人工审查和完整的CI流水线测试打消大家对代码质量的顾虑。收集数据展示价值我们简单统计了使用Harness前后完成一个标准CRUD模块的平均时间。数据表明从原来的2-3人日下降到了0.5人日包括人工审查和微调的时间这成为了最有说服力的推广材料。6. 效果评估与未来演进经过三个月的实践这套AI规范驱动编程的Harness已经成为了我们团队的标准开发装备之一。量化效果开发效率对于模式固定的业务模块如各种管理后台的增删改查开发速度提升了60%以上。代码一致性新生成的代码在风格、结构和命名上高度一致新成员阅读代码的门槛降低。代码审查效率因为大部分低级规范问题缩进、导入、基础验证已在生成时解决审查者可以更专注于业务逻辑和设计问题。知识沉淀.ai/context目录成了项目最好的活文档新成员通过阅读这些文件能快速理解项目全貌。未来规划上下文向量化计划将代码库、文档导入到向量数据库如ChromaDB实现更智能的语义检索和上下文注入彻底解决上下文长度和精度问题。个性化Prompt调优允许团队成员在共享基础模板上保存自己常用的、针对特定任务的微调Prompt兼顾统一性与个人效率。闭环学习建立反馈机制当人工修改了AI生成的代码后能将这些修改作为“正确样本”记录下来用于微调本地的轻量级模型让AI越来越懂我们项目的“脾气”。从我个人的体验来看AI规范驱动编程不是要取代开发者而是将开发者从重复、繁琐、低创造性的劳动中解放出来。它更像是一个严格遵循团队规范、不知疲倦的初级工程师能高质量地完成你指派的具体任务。而你的角色则更多地转向了架构设计、复杂问题拆解、核心算法实现以及最终的决策与审查。这套Harness就是你和这位“AI同事”之间高效协作的桥梁与工作手册。