尧图网页设计 
1. “能用”和“好用”之间隔着整整一条工程化鸿沟我第一次让AI写出能跑通的React组件时兴奋得在工位上敲了三下键盘——不是因为代码多漂亮而是它居然没报错。那会儿刚接触Claude Code输入一句“写个带搜索功能的商品列表”回车5秒后生成的JSX真能渲染、真能过滤、真能点按钮。我截图发到技术群配文“AI编程成了。”三个月后我在同一个项目里删掉了所有AI生成的代码。不是它错了是它太“对”了函数命名像教科书状态管理逻辑清晰甚至自动加了PropTypes校验——可当产品临时要求把搜索框从顶部移到侧边栏、把商品卡片从横向滚动改成网格布局、把API响应格式从{items: []}改成{data: {list: []}}时我花了6小时改代码其中4小时在翻Chat记录、比对提示词、重试生成、手动缝合碎片。AI写的不是“可维护的系统”而是一份“一次性交付的快照”。这就是“能用”和“好用”的本质区别能用是单点任务的瞬时胜利好用是全生命周期的持续交付能力。它不取决于模型参数有多大、上下文有多长、是否支持多模态而取决于你有没有把AI塞进工程流水线里——让它像Git一样被版本控制像Jenkins一样被触发构建像SonarQube一样被扫描质量像Swagger一样被契约约束。热搜词里反复出现的CLAUDE.md、AGENTS.md、OpenSpec根本不是什么新工具而是三份“工程化说明书”CLAUDE.md是你给AI写的《岗位说明书》——明确它负责哪块、边界在哪、输入输出格式怎么约定AGENTS.md是你设计的《协作流程图》——定义谁发起任务、谁审核结果、谁兜底异常、谁归档知识OpenSpec是你和AI签的《服务契约》——用机器可读的YAML/JSON描述接口、数据结构、错误码、调用链路让AI不再靠猜而是按契约履约。没有这三样东西AI编程永远停留在“程序员辅助模式”有了它们AI才真正成为团队里那个沉默但可靠的“第三位工程师”。这不是玄学是我在光大证券做量化交易系统AI重构时踩出来的路把原来3人周迭代的行情数据清洗模块变成1人AI日更的稳定服务关键不是换了个更强的模型而是先写了27页OpenSpec文档再让AI对着契约写代码——生成的代码第一次提交就通过了全部单元测试连Mock数据都严格遵循Schema定义。下面我就拆开这三件套告诉你每一份文档怎么写、为什么这么写、写错会掉进什么坑。2.CLAUDE.md给AI立下的第一份岗位说明书不是提示词是权责契约很多人把CLAUDE.md当成“高级提示词模板”这是最大的误解。提示词是临时指令CLAUDE.md是岗位契约——它定义的是AI在你团队里的角色定位、能力边界、交付标准和追责机制。我见过太多团队把这份文档写成“如何让Claude写得更好”的技巧集结果AI越写越飘最后代码里全是// TODO: 这里需要人工确认的幽灵注释。2.1 为什么必须用Markdown文档而不是存在Notion或飞书里的“提示词库”因为工程化第一原则是可版本化、可审计、可继承。当你把CLAUDE.md放在项目根目录下和package.json、.gitignore放在一起它就自动获得Git的全部能力git blame CLAUDE.md能查出是谁在上周五下午三点修改了“禁止生成console.log”的条款git diff v1.2..v1.3 CLAUDE.md能清晰看到新增了“所有API调用必须包含超时配置”的硬性要求新入职的同事git clone后第一件事就是cat CLAUDE.md而不是翻十页飞书文档找“最佳实践”。更重要的是现代IDE如IntelliJ IDEA、VS Code已支持基于文件路径的智能提示。当你在src/api/user.ts里敲// claude: generate service for user login编辑器能自动读取根目录CLAUDE.md中的service_generation_rules区块给出符合契约的补全建议——这比任何插件的模糊匹配都精准。提示不要把CLAUDE.md写成“AI使用手册”。它只回答三个问题它能做什么例如生成TypeScript接口定义、编写Jest测试用例、转换JSON Schema为Zod Schema它不能做什么例如不得生成数据库迁移SQL、不得调用未声明的第三方SDK、不得硬编码密钥它必须怎么做例如所有HTTP请求必须使用axios.create({timeout: 5000})、所有错误处理必须返回ResultT, Error泛型、所有日期格式必须为ISO 86012.2 我们团队CLAUDE.md的核心结构与真实条款我们当前版本的CLAUDE.md共分5个区块每个区块都经过至少3次线上事故倒逼修订2.2.1role_and_scope划定AI的“工作辖区”## role_and_scope - **核心角色**前端业务逻辑实现者非架构师、非DBA、非运维 - **绝对禁区** - 不得修改webpack.config.js、tsconfig.json、jest.config.ts等构建/配置文件 - 不得生成涉及JWT签发、密码哈希、敏感数据加密的代码 - 不得在src/utils/外创建新工具函数目录 - **默认能力** - 可生成符合React 18 TypeScript 5.0语法的组件、Hook、Service - 可基于OpenAPI 3.0规范生成Axios Service封装 - 可为现有函数生成Jest测试用例覆盖率目标语句覆盖≥85%这个区块救过我们两次一次是新人误让AI“优化”了Webpack配置导致CI构建失败2小时另一次是AI在生成登录接口时自动加了bcrypt.hashSync()被SonarQube安全扫描直接拦截。现在所有AI生成代码都带// scope: frontend_logic_only标记CI流水线会用正则扫描并拒绝含require(crypto)或import { PrismaClient } from prisma/client的提交。2.2.2input_formatting统一AI的“理解入口”AI不是人它没有上下文感知力只有token匹配精度。我们强制所有指令必须遵循三段式结构## input_formatting 所有向AI发起的指令必须包含 1. **CONTEXT**必填当前文件路径、相关模块名称、最近一次Git commit message摘要 示例CONTEXT: src/components/ProductList.tsx | module: product-catalog | last-commit: feat(product): add search debounce 2. **TASK**必填动词开头的原子操作禁止复合指令 ✅ 正确TASK: generate a useSearch hook that accepts query string and returns filtered products ❌ 错误TASK: write the product list page with search, pagination and sorting 3. **CONSTRAINTS**选填不超过3条具体限制 示例CONSTRAINTS: - use React.memo for ProductCard - debounce delay: 300ms - filter logic must match backend API spec v2.1这个结构让AI输出稳定性提升47%我们统计了2000次生成任务。关键在于CONTEXT字段——它把模糊的“当前页面”变成了精确的src/components/ProductList.tsxAI就能准确识别该文件已有的Product类型定义、已导入的useApiHook、已存在的ProductCard组件避免重复造轮子。2.2.3output_formatting定义AI的“交付物标准”这才是真正区分“能用”和“好用”的分水岭。我们不要“能跑通的代码”我们要“能直接合并的代码”。## output_formatting AI生成的所有代码必须 - **零注释**禁止// TODO、// FIXME、// This is temporary等占位注释由人类工程师添加 - **零假设**禁止if (process.env.NODE_ENV development)等环境判断由构建配置处理 - **零魔法值**数字/字符串必须有常量名且定义在src/constants/下 ✅ 正确const SEARCH_DEBOUNCE_MS 300; ... debounce(searchFn, SEARCH_DEBOUNCE_MS) ❌ 错误debounce(searchFn, 300) - **强类型优先**所有函数参数、返回值、变量必须显式标注TypeScript类型禁止any、object、Function - **契约对齐**若涉及API调用必须严格遵循src/specs/product-api.yaml中定义的request/response schema这条规则执行后Code Review时间缩短60%。以前PR里常见“请把这里的any改成具体类型”现在AI生成的代码类型错误率低于0.3%我们用TypeScript编译器API做了自动化检测。2.3 实战避坑那些看似合理却埋雷的条款陷阱条款“AI必须生成100%无bug代码”→ 现实AI无法保证逻辑正确性只能保证语法正确和契约合规。我们改为“AI生成代码必须通过全部单元测试测试用例由AI同步生成并标注generated-by-claude”。陷阱条款“禁止生成console.log”→ 现实调试阶段需要日志。我们改为“生产环境禁用console.log开发环境日志必须使用logger.debug()且分级可控日志格式遵循[MODULE][ACTION] message”。陷阱条款“所有代码必须符合Airbnb ESLint规则”→ 现实规则冲突频发。我们改为“采用项目根目录.eslintrc.js配置AI生成代码需通过eslint --fix自动修复未通过则拒绝提交”。这些调整不是妥协而是把AI真正当作一个需要明确KPI的工程师——它的绩效考核指标就是CLAUDE.md里白纸黑字写的条款。3.AGENTS.md构建AI协作的“指挥链”不是自动化脚本是人机协同协议很多团队卡在AI工程化的第二关不是不会用AI而是不知道“什么时候该叫它怎么叫它叫完之后谁来收尾”。他们把AI当万能胶水哪里缺代码就糊一坨结果系统变成由无数AI片段拼接的“千层饼”每一层都美味但叠在一起就塌方。AGENTS.md要解决的正是这个“指挥失灵”问题。它不是写给AI看的是写给人类看的——告诉每个角色你在AI协作流程中站哪个位置、举什么旗、吹什么哨、守哪道关。3.1 为什么不能用Zapier/Make这类自动化工具替代AGENTS.md因为AI协作的本质不是“触发-执行”而是“协商-决策-验证”。Zapier能帮你把GitHub PR通知发到钉钉但它无法判断“这个PR里AI生成的代码是否改变了核心交易逻辑”、“这个API变更是否需要同步更新OpenAPI文档”、“这个UI改动是否影响了无障碍访问标准”AGENTS.md定义的是人类决策点而不是机器执行点。它把AI协作拆解为四个不可跳过的环节环节触发条件负责人关键动作退出标准Initiate发起需求明确、边界清晰、有OpenSpec依据开发工程师编写CONTEXTTASKCONSTRAINTS指令关联对应OpenSpec文件指令通过claude-lint静态检查验证格式/引用/权限Generate生成指令合法、资源就绪AI引擎生成代码测试文档草案输出通过output_formatting校验测试覆盖率≥85%Validate验证生成完成、CI流水线就绪QA工程师执行端到端测试、安全扫描、性能基线对比无P0/P1缺陷性能波动≤5%安全漏洞数0Integrate集成验证通过、文档就绪主程/架构师合并代码、更新OpenSpec、归档CLAUDE.md修订记录PR被批准OpenSpec版本号递增知识库更新这个流程里AI只负责第二步“Generate”其他三步全是人类把关。我们曾尝试跳过Validate环节让AI自测——结果它生成的测试用例完美覆盖了自己写的代码却漏掉了与支付模块的耦合逻辑上线后导致订单重复创建。3.2AGENTS.md中的“红绿灯机制”用颜色定义协作节奏我们用交通灯颜色管理AI协作的紧急程度和人力投入这比“高/中/低优先级”直观得多3.2.1 绿灯任务AI可独立交付人类仅做抽检适用场景标准化、低风险、高频次的代码生成示例为新API端点生成TypeScript客户端SDK流程开发工程师提交OpenAPI 3.0 YAML到src/specs/CI流水线自动触发claude-sdk-generator基于CLAUDE.md规则生成代码测试README自动创建Draft PR主程每日抽检3个绿灯PR通过则合并否则退回并更新CLAUDE.md注意绿灯任务必须满足三个硬条件——OpenAPI文档已通过openapi-validator校验接口无x-internal: true标记即非内部接口请求/响应body schema中无anyOf/oneOf复杂联合类型我们90%的API SDK生成走绿灯平均交付时间从2小时压缩到8分钟。3.2.2 黄灯任务AI生成人类深度参与双人结对适用场景业务逻辑复杂、跨模块耦合、有状态变更示例重构用户积分计算引擎涉及订单、活动、风控三个服务流程架构师编写AGENTS.md#yellow-task-template明确各模块边界和契约开发工程师与QA工程师组成“黄灯小组”共同编写CONTEXTTASKCONSTRAINTSAI生成代码后小组进行“三明治评审”第一层AI生成的代码是否符合CLAUDE.md技术合规第二层是否覆盖所有业务场景需求合规第三层与上下游服务的调用是否幂等架构合规评审通过后由QA工程师主导集成测试黄灯任务的关键是“双人结对”——AI生成的代码必须有两个人同时签字确认。我们规定任何黄灯PR缺少QA工程师的LGTM评论CI将拒绝合并。3.2.3 红灯任务人类主导AI仅作辅助严禁自主生成适用场景核心资金流、安全敏感、监管合规、架构演进示例交易结算引擎升级、用户身份认证体系重构、GDPR数据删除流程流程必须召开红灯任务启动会参会者包括主程、安全官、法务代表、领域专家会议产出《红灯任务契约》明确哪些模块允许AI辅助如日志格式化、监控埋点哪些模块禁止AI触碰如签名验签、余额扣减所有AI辅助代码必须加// red-light: assisted-by-claude标记开发过程全程录屏AI交互记录存入审计日志红灯任务不是不用AI而是把AI降级为“高级文本处理器”。比如在写结算引擎时AI可以帮我们把监管文档里的“T1清算”要求转成注释但绝不允许它生成deductBalance()函数。3.3 真实踩坑当“黄灯”被当成“绿灯”处理去年Q3我们有个黄灯任务——重构优惠券发放服务。开发工程师觉得“不就是改个Redis key格式”擅自走绿灯流程。AI生成的代码完美符合CLAUDE.md测试全部通过CI自动合并。上线后第三天风控系统报警同一张优惠券被并发发放了17次。根因分析发现AI生成的getCacheKey()函数用了Date.now()作为key的一部分而服务是集群部署不同节点时间差导致key不一致缓存穿透。这个Bug暴露了AGENTS.md的致命漏洞我们没定义“并发安全”是否属于黄灯任务的强制评审项。补救措施在AGENTS.md#yellow-task-template中新增条款“所有涉及缓存、锁、计数器的操作必须提供并发压测报告≥1000 TPS”在CI流水线增加concurrency-checker插件自动扫描AI生成代码中的Date.now()、Math.random()、new Date()等非幂等操作从此“时间相关操作”成为黄灯任务的默认红区。4.OpenSpec让AI从“猜意图”到“守契约”不是文档是服务契约如果说CLAUDE.md是给AI定岗AGENTS.md是给流程定规那么OpenSpec就是给交付定契——它把模糊的“我要一个用户登录功能”变成机器可读、AI可执行、人类可验证的精确契约。热搜词里反复出现的openspec使用教程、openspec官方文档背后藏着一个残酷真相90%的AI编程失败不是因为模型不行而是因为契约缺失。AI不是人它不会问“你到底想要什么”它只会拼命匹配你提示词里最频繁出现的token。你写“用户登录”它可能生成一个带JWT签发的完整认证服务你写“用户登录界面”它可能只给你一个带表单的React组件。没有契约AI就在猜谜。OpenSpec就是终结猜谜的武器。它不是Swagger的替代品而是Swagger的增强层——在OpenAPI 3.0基础上增加了AI可执行的元数据、质量约束和演化规则。4.1OpenSpec与传统OpenAPI的本质差异维度传统OpenAPI 3.0OpenSpec目标读者人类开发者、前端工程师、测试人员AI代码生成器、CI质量门禁、契约验证引擎核心字段paths,components/schemas,responses新增x-ai-constraints,x-evolution-rules,x-quality-gates验证方式人工阅读、Postman测试自动化扫描openspec-validateCLI、AI生成前校验、CI流水线拦截演化管理版本号递增v1→v2无兼容性声明显式声明breaking-changes: [field_removed, type_changed]AI生成时自动拒绝不兼容变更我们团队的product-api.yaml第一行不再是openapi: 3.0.0而是openapi: 3.0.0 info: title: Product Catalog API version: 2.3.1 x-ai-constraints: # 这些约束会被AI生成器实时读取 response_schema_strictness: strict # 禁止AI返回额外字段 error_handling: standardize # 所有错误必须返回统一Error Schema pagination: cursor_based # 分页必须用cursor禁用offset/limit x-evolution-rules: # 定义API如何安全演进 - rule: adding new optional field is allowed - rule: changing field type from string to number is breaking - rule: removing deprecated field requires 2 versions grace period x-quality-gates: # CI流水线的质量门禁 - gate: response_time_p95 200ms - gate: error_rate 0.1% - gate: security_scan_pass: true当AI要生成GET /products的Service时它首先读取x-ai-constraints就知道返回数据必须严格匹配components/schemas/ProductListResponse不能多也不能少错误响应必须用components/schemas/StandardError不能自己发明{code: 50001, msg: xxx}分页参数必须是?cursorxxxlimit20不能用?page1size20。4.2OpenSpec驱动的AI生成全流程以生成src/services/productService.ts为例整个流程完全由OpenSpec驱动4.2.1 步骤1契约解析AI启动前AI引擎加载src/specs/product-api.yaml执行以下校验检查x-ai-constraints.response_schema_strictness strict→ 启用Schema严格校验模式解析paths[/products][get][responses][200][content][application/json][schema]→ 获取返回类型定义提取x-quality-gates中response_time_p95阈值 → 生成代码时自动注入性能监控埋点4.2.2 步骤2代码生成AI执行中AI根据契约生成TypeScript代码关键特征所有DTO类型直接从OpenAPI Schema生成而非手写// 自动生成非手写 export interface ProductListResponse { data: Array{ id: string; name: string; price: number; tags?: Arraystring; }; next_cursor?: string; }HTTP调用强制使用预设的apiClient已配置超时、重试、监控// 自动生成含性能埋点 export const getProductList async (params: { cursor?: string; limit?: number }) { const start performance.now(); try { const res await apiClient.getProductListResponse(/products, { params }); performance.mark(product-list-success-${Date.now()}); return res.data; } catch (e) { performance.mark(product-list-error-${Date.now()}); throw e; } };错误处理统一// 自动生成符合x-ai-constraints.error_handling if (res.status 400) { const error res.data as StandardError; throw new ApiError(error.code, error.message, error.details); }4.2.3 步骤3契约验证AI交付后生成代码提交前CI流水线运行# 1. 验证代码是否符合OpenSpec契约 openspec-validate --spec src/specs/product-api.yaml --code src/services/productService.ts # 2. 验证生成的测试用例是否覆盖所有2xx/4xx响应 jest --coverage --testPathPatternproductService.test.ts # 3. 静态扫描是否引入不合规依赖 npx eslint --rule no-restricted-imports: [2, {patterns: [axios]}] src/services/productService.ts只有全部通过PR才能进入Validate环节。4.3OpenSpec实战从“没有它”到“有它”的质变我们做过对照实验同一组工程师用相同Claude模型分别处理两个相似需求——组A无OpenSpec需求“获取用户收藏商品列表”提示词“写个API调用函数返回用户收藏的商品”。结果生成了5个版本最终版返回{items: []}但产品实际需要{data: {list: []}, meta: {total: 100}}返工3次。组B有OpenSpec需求指向src/specs/user-favorite-api.yamlAI自动读取paths[/users/{id}/favorites][get][responses][200]。结果首次生成即符合契约返回类型、错误处理、分页参数全部正确测试覆盖率92%。差距不在AI而在契约。OpenSpec把“人话需求”翻译成“机器语言”让AI从“尽力而为”变成“必须履约”。提示OpenSpec不是一劳永逸的文档。我们每周四下午固定1小时做OpenSpec健康度检查扫描所有x-ai-constraints字段确认是否有过期规则如response_schema_strictness: loose已被弃用对比Git历史检查是否有API变更未同步更新x-evolution-rules运行openspec-diff工具生成本周契约变更报告邮件发送给全体工程师这确保OpenSpec始终是活的契约而不是尘封的PDF。5. 三件套协同当CLAUDE.md、AGENTS.md、OpenSpec开始互相咬合单独看CLAUDE.md、AGENTS.md、OpenSpec它们只是三份文档。但当它们开始互相引用、互相校验、互相驱动时AI编程才真正完成从“能用”到“好用”的跃迁。这种协同不是理论设计而是我们在MIT AI编程课程项目中实打实跑出来的闭环。当时要做一个校园二手书交易平台需求是“学生能发布、搜索、购买书籍”团队6人工期4周。没有三件套时我们花了2周在AI生成的代码里修Bug引入三件套后第3天就交付了MVP第7天完成全栈上线。5.1 协同起点OpenSpec驱动CLAUDE.md条款动态更新OpenSpec不是静态文档它是AI生成的源头活水。当API契约变化时CLAUDE.md必须自动适应。我们用openspec-sync工具实现联动当src/specs/book-api.yaml中x-ai-constraints.response_schema_strictness从loose改为strict时工具自动扫描CLAUDE.md找到output_formatting区块将原条款AI生成代码可返回额外字段替换为AI生成代码必须严格匹配OpenSpec定义的Schema禁止返回额外字段并提交PR标题为[AUTO] Update CLAUDE.md to enforce strict schema matching per book-api.yaml v1.4。这个机制让我们避免了“契约已更新但AI还在按旧规则生成”的经典陷阱。过去半年CLAUDE.md的23次更新中17次由OpenSpec变更自动触发。5.2 协同枢纽AGENTS.md用OpenSpec版本号锁定AI生成上下文在AGENTS.md的Initiate环节我们强制要求指令中必须包含OpenSpec版本引用CONTEXT: src/services/bookService.ts | module: book-marketplace | last-commit: feat(book): add wishlist feature TASK: generate wishlist service functions for adding/removing books CONSTRAINTS: - use OpenSpec v1.4 (src/specs/book-api.yaml) - all endpoints must include x-correlation-id header - error responses must match components/schemas/WishlistError这个use OpenSpec v1.4不是装饰而是AI生成器的“上下文锚点”。AI引擎会加载book-api.yamlv1.4版本而非最新版确保生成代码与当前分支契约一致校验x-correlation-id是否在paths[/wishlist][post][parameters]中定义提取WishlistErrorSchema生成对应的TypeScript类型。如果没有这个锚点AI可能加载了v1.5已废弃x-correlation-id生成的代码在CI中直接失败。5.3 协同终点CLAUDE.md条款成为AGENTS.md验证环节的自动化检查项Validate环节的自动化扫描不只是跑测试更是用CLAUDE.md当尺子量AI的交付物。我们开发了claude-linterCLI工具它读取CLAUDE.md中的output_formatting条款并对AI生成代码做静态分析扫描console.log出现次数 → 验证“零注释”条款检查const声明数量与魔法值数量比 → 验证“零魔法值”条款统计any/object类型出现位置 → 验证“强类型优先”条款匹配// scope:标记与CLAUDE.md#role_and_scope→ 验证“工作辖区”条款这个工具集成在CI中任何违反CLAUDE.md的代码都会在Validate环节被拦截错误信息直接指向CLAUDE.md的具体条款编号如CLAUDE.md#2.2.3-3开发者一眼就知道该去改哪条契约。5.4 真实协同案例光大证券股市数据服务的AI交付在光大证券的项目中我们需要快速交付一个“实时行情历史K线交易信号”服务。传统方式需3名后端2名前端1名测试周期6周。我们用三件套协同Step 1架构师用OpenSpec定义market-data-api.yaml明确/quote返回{symbol, price, change_pct}/kline返回{timestamp, open, high, low, close, volume}/signal返回{type: buy|sell, confidence: 0.8}Step 2开发工程师按AGENTS.md黄灯流程编写指令并引用OpenSpec v2.1Step 3AI生成src/services/marketService.tsclaude-linter扫描通过openspec-validate校验通过Step 4QA工程师执行AGENTS.md#Validate重点测试/signal的置信度阈值是否可配置OpenSpec中x-ai-constraints已声明configurable_threshold: trueStep 5主程审核发现/kline返回的volume字段单位应为millions而非units立即更新OpenSpec并触发CLAUDE.md自动同步。整个服务从需求提出到上线耗时11天其中AI生成代码仅用27分钟。关键不是AI快而是三件套让每一次生成都精准命中契约每一次验证都有据可依每一次迭代都闭环可控。6. 工程化落地的硬核检查清单别让AI编程死在第一步我知道看到这里你可能已经打开编辑器想写CLAUDE.md了。但请先停一下——我见过太多团队倒在第一步文档写得漂亮但没人用、没人审、没人更新最后变成项目根目录下最孤独的Markdown文件。工程化不是写文档是建机制。下面这份检查清单是我们团队踩坑后提炼的“生存指南”每一条都对应一个真实翻车现场6.1 文档即代码CLAUDE.md必须通过CI流水线校验必须做在CI中添加步骤运行markdownlint CLAUDE.md禁止header-increment标题跳级、no-multiple-blanks多余空行、fenced-code-language代码块缺失语言标识必须做用正则扫描CLAUDE.md中的TODO、FIXME、XXX发现即失败——文档里不能有“待办事项”只有“已决议项”必须做git diff检测CLAUDE.md变更若新增role_and_scope条款必须关联Jira需求ID如PROJ-1234否则CI拒绝合并。我们曾因CLAUDE.md里一个// TODO: add security rules注释导致CI流水线阻塞3小时。现在所有条款都必须是“已完成”状态。6.2 权限即契约AGENTS.md的每个角色必须有明确Owner必须做在AGENTS.md顶部声明owners区块指定Initiate、Validate、Integrate环节的负责人姓名/工号每月更新必须做Validate环节的QA工程师必须有openspec-validate工具的执行权限且其账号绑定到CI流水线必须做Integrate环节的主程必须拥有OpenSpec仓库的write权限确保契约更新与代码合并同步。曾有团队把AGENTS.md写成“理想流程”结果Validate环节没人认领AI生成的代码直接进主干。现在每个环节Owner的名字都加粗显示且链接到企业微信个人主页。6.3 契约即资产 AI编程工程化三件套：CLAUDE.md、AGENTS.md与OpenSpec实战指南
1. “能用”和“好用”之间隔着整整一条工程化鸿沟我第一次让AI写出能跑通的React组件时兴奋得在工位上敲了三下键盘——不是因为代码多漂亮而是它居然没报错。那会儿刚接触Claude Code输入一句“写个带搜索功能的商品列表”回车5秒后生成的JSX真能渲染、真能过滤、真能点按钮。我截图发到技术群配文“AI编程成了。”三个月后我在同一个项目里删掉了所有AI生成的代码。不是它错了是它太“对”了函数命名像教科书状态管理逻辑清晰甚至自动加了PropTypes校验——可当产品临时要求把搜索框从顶部移到侧边栏、把商品卡片从横向滚动改成网格布局、把API响应格式从{items: []}改成{data: {list: []}}时我花了6小时改代码其中4小时在翻Chat记录、比对提示词、重试生成、手动缝合碎片。AI写的不是“可维护的系统”而是一份“一次性交付的快照”。这就是“能用”和“好用”的本质区别能用是单点任务的瞬时胜利好用是全生命周期的持续交付能力。它不取决于模型参数有多大、上下文有多长、是否支持多模态而取决于你有没有把AI塞进工程流水线里——让它像Git一样被版本控制像Jenkins一样被触发构建像SonarQube一样被扫描质量像Swagger一样被契约约束。热搜词里反复出现的CLAUDE.md、AGENTS.md、OpenSpec根本不是什么新工具而是三份“工程化说明书”CLAUDE.md是你给AI写的《岗位说明书》——明确它负责哪块、边界在哪、输入输出格式怎么约定AGENTS.md是你设计的《协作流程图》——定义谁发起任务、谁审核结果、谁兜底异常、谁归档知识OpenSpec是你和AI签的《服务契约》——用机器可读的YAML/JSON描述接口、数据结构、错误码、调用链路让AI不再靠猜而是按契约履约。没有这三样东西AI编程永远停留在“程序员辅助模式”有了它们AI才真正成为团队里那个沉默但可靠的“第三位工程师”。这不是玄学是我在光大证券做量化交易系统AI重构时踩出来的路把原来3人周迭代的行情数据清洗模块变成1人AI日更的稳定服务关键不是换了个更强的模型而是先写了27页OpenSpec文档再让AI对着契约写代码——生成的代码第一次提交就通过了全部单元测试连Mock数据都严格遵循Schema定义。下面我就拆开这三件套告诉你每一份文档怎么写、为什么这么写、写错会掉进什么坑。2.CLAUDE.md给AI立下的第一份岗位说明书不是提示词是权责契约很多人把CLAUDE.md当成“高级提示词模板”这是最大的误解。提示词是临时指令CLAUDE.md是岗位契约——它定义的是AI在你团队里的角色定位、能力边界、交付标准和追责机制。我见过太多团队把这份文档写成“如何让Claude写得更好”的技巧集结果AI越写越飘最后代码里全是// TODO: 这里需要人工确认的幽灵注释。2.1 为什么必须用Markdown文档而不是存在Notion或飞书里的“提示词库”因为工程化第一原则是可版本化、可审计、可继承。当你把CLAUDE.md放在项目根目录下和package.json、.gitignore放在一起它就自动获得Git的全部能力git blame CLAUDE.md能查出是谁在上周五下午三点修改了“禁止生成console.log”的条款git diff v1.2..v1.3 CLAUDE.md能清晰看到新增了“所有API调用必须包含超时配置”的硬性要求新入职的同事git clone后第一件事就是cat CLAUDE.md而不是翻十页飞书文档找“最佳实践”。更重要的是现代IDE如IntelliJ IDEA、VS Code已支持基于文件路径的智能提示。当你在src/api/user.ts里敲// claude: generate service for user login编辑器能自动读取根目录CLAUDE.md中的service_generation_rules区块给出符合契约的补全建议——这比任何插件的模糊匹配都精准。提示不要把CLAUDE.md写成“AI使用手册”。它只回答三个问题它能做什么例如生成TypeScript接口定义、编写Jest测试用例、转换JSON Schema为Zod Schema它不能做什么例如不得生成数据库迁移SQL、不得调用未声明的第三方SDK、不得硬编码密钥它必须怎么做例如所有HTTP请求必须使用axios.create({timeout: 5000})、所有错误处理必须返回ResultT, Error泛型、所有日期格式必须为ISO 86012.2 我们团队CLAUDE.md的核心结构与真实条款我们当前版本的CLAUDE.md共分5个区块每个区块都经过至少3次线上事故倒逼修订2.2.1role_and_scope划定AI的“工作辖区”## role_and_scope - **核心角色**前端业务逻辑实现者非架构师、非DBA、非运维 - **绝对禁区** - 不得修改webpack.config.js、tsconfig.json、jest.config.ts等构建/配置文件 - 不得生成涉及JWT签发、密码哈希、敏感数据加密的代码 - 不得在src/utils/外创建新工具函数目录 - **默认能力** - 可生成符合React 18 TypeScript 5.0语法的组件、Hook、Service - 可基于OpenAPI 3.0规范生成Axios Service封装 - 可为现有函数生成Jest测试用例覆盖率目标语句覆盖≥85%这个区块救过我们两次一次是新人误让AI“优化”了Webpack配置导致CI构建失败2小时另一次是AI在生成登录接口时自动加了bcrypt.hashSync()被SonarQube安全扫描直接拦截。现在所有AI生成代码都带// scope: frontend_logic_only标记CI流水线会用正则扫描并拒绝含require(crypto)或import { PrismaClient } from prisma/client的提交。2.2.2input_formatting统一AI的“理解入口”AI不是人它没有上下文感知力只有token匹配精度。我们强制所有指令必须遵循三段式结构## input_formatting 所有向AI发起的指令必须包含 1. **CONTEXT**必填当前文件路径、相关模块名称、最近一次Git commit message摘要 示例CONTEXT: src/components/ProductList.tsx | module: product-catalog | last-commit: feat(product): add search debounce 2. **TASK**必填动词开头的原子操作禁止复合指令 ✅ 正确TASK: generate a useSearch hook that accepts query string and returns filtered products ❌ 错误TASK: write the product list page with search, pagination and sorting 3. **CONSTRAINTS**选填不超过3条具体限制 示例CONSTRAINTS: - use React.memo for ProductCard - debounce delay: 300ms - filter logic must match backend API spec v2.1这个结构让AI输出稳定性提升47%我们统计了2000次生成任务。关键在于CONTEXT字段——它把模糊的“当前页面”变成了精确的src/components/ProductList.tsxAI就能准确识别该文件已有的Product类型定义、已导入的useApiHook、已存在的ProductCard组件避免重复造轮子。2.2.3output_formatting定义AI的“交付物标准”这才是真正区分“能用”和“好用”的分水岭。我们不要“能跑通的代码”我们要“能直接合并的代码”。## output_formatting AI生成的所有代码必须 - **零注释**禁止// TODO、// FIXME、// This is temporary等占位注释由人类工程师添加 - **零假设**禁止if (process.env.NODE_ENV development)等环境判断由构建配置处理 - **零魔法值**数字/字符串必须有常量名且定义在src/constants/下 ✅ 正确const SEARCH_DEBOUNCE_MS 300; ... debounce(searchFn, SEARCH_DEBOUNCE_MS) ❌ 错误debounce(searchFn, 300) - **强类型优先**所有函数参数、返回值、变量必须显式标注TypeScript类型禁止any、object、Function - **契约对齐**若涉及API调用必须严格遵循src/specs/product-api.yaml中定义的request/response schema这条规则执行后Code Review时间缩短60%。以前PR里常见“请把这里的any改成具体类型”现在AI生成的代码类型错误率低于0.3%我们用TypeScript编译器API做了自动化检测。2.3 实战避坑那些看似合理却埋雷的条款陷阱条款“AI必须生成100%无bug代码”→ 现实AI无法保证逻辑正确性只能保证语法正确和契约合规。我们改为“AI生成代码必须通过全部单元测试测试用例由AI同步生成并标注generated-by-claude”。陷阱条款“禁止生成console.log”→ 现实调试阶段需要日志。我们改为“生产环境禁用console.log开发环境日志必须使用logger.debug()且分级可控日志格式遵循[MODULE][ACTION] message”。陷阱条款“所有代码必须符合Airbnb ESLint规则”→ 现实规则冲突频发。我们改为“采用项目根目录.eslintrc.js配置AI生成代码需通过eslint --fix自动修复未通过则拒绝提交”。这些调整不是妥协而是把AI真正当作一个需要明确KPI的工程师——它的绩效考核指标就是CLAUDE.md里白纸黑字写的条款。3.AGENTS.md构建AI协作的“指挥链”不是自动化脚本是人机协同协议很多团队卡在AI工程化的第二关不是不会用AI而是不知道“什么时候该叫它怎么叫它叫完之后谁来收尾”。他们把AI当万能胶水哪里缺代码就糊一坨结果系统变成由无数AI片段拼接的“千层饼”每一层都美味但叠在一起就塌方。AGENTS.md要解决的正是这个“指挥失灵”问题。它不是写给AI看的是写给人类看的——告诉每个角色你在AI协作流程中站哪个位置、举什么旗、吹什么哨、守哪道关。3.1 为什么不能用Zapier/Make这类自动化工具替代AGENTS.md因为AI协作的本质不是“触发-执行”而是“协商-决策-验证”。Zapier能帮你把GitHub PR通知发到钉钉但它无法判断“这个PR里AI生成的代码是否改变了核心交易逻辑”、“这个API变更是否需要同步更新OpenAPI文档”、“这个UI改动是否影响了无障碍访问标准”AGENTS.md定义的是人类决策点而不是机器执行点。它把AI协作拆解为四个不可跳过的环节环节触发条件负责人关键动作退出标准Initiate发起需求明确、边界清晰、有OpenSpec依据开发工程师编写CONTEXTTASKCONSTRAINTS指令关联对应OpenSpec文件指令通过claude-lint静态检查验证格式/引用/权限Generate生成指令合法、资源就绪AI引擎生成代码测试文档草案输出通过output_formatting校验测试覆盖率≥85%Validate验证生成完成、CI流水线就绪QA工程师执行端到端测试、安全扫描、性能基线对比无P0/P1缺陷性能波动≤5%安全漏洞数0Integrate集成验证通过、文档就绪主程/架构师合并代码、更新OpenSpec、归档CLAUDE.md修订记录PR被批准OpenSpec版本号递增知识库更新这个流程里AI只负责第二步“Generate”其他三步全是人类把关。我们曾尝试跳过Validate环节让AI自测——结果它生成的测试用例完美覆盖了自己写的代码却漏掉了与支付模块的耦合逻辑上线后导致订单重复创建。3.2AGENTS.md中的“红绿灯机制”用颜色定义协作节奏我们用交通灯颜色管理AI协作的紧急程度和人力投入这比“高/中/低优先级”直观得多3.2.1 绿灯任务AI可独立交付人类仅做抽检适用场景标准化、低风险、高频次的代码生成示例为新API端点生成TypeScript客户端SDK流程开发工程师提交OpenAPI 3.0 YAML到src/specs/CI流水线自动触发claude-sdk-generator基于CLAUDE.md规则生成代码测试README自动创建Draft PR主程每日抽检3个绿灯PR通过则合并否则退回并更新CLAUDE.md注意绿灯任务必须满足三个硬条件——OpenAPI文档已通过openapi-validator校验接口无x-internal: true标记即非内部接口请求/响应body schema中无anyOf/oneOf复杂联合类型我们90%的API SDK生成走绿灯平均交付时间从2小时压缩到8分钟。3.2.2 黄灯任务AI生成人类深度参与双人结对适用场景业务逻辑复杂、跨模块耦合、有状态变更示例重构用户积分计算引擎涉及订单、活动、风控三个服务流程架构师编写AGENTS.md#yellow-task-template明确各模块边界和契约开发工程师与QA工程师组成“黄灯小组”共同编写CONTEXTTASKCONSTRAINTSAI生成代码后小组进行“三明治评审”第一层AI生成的代码是否符合CLAUDE.md技术合规第二层是否覆盖所有业务场景需求合规第三层与上下游服务的调用是否幂等架构合规评审通过后由QA工程师主导集成测试黄灯任务的关键是“双人结对”——AI生成的代码必须有两个人同时签字确认。我们规定任何黄灯PR缺少QA工程师的LGTM评论CI将拒绝合并。3.2.3 红灯任务人类主导AI仅作辅助严禁自主生成适用场景核心资金流、安全敏感、监管合规、架构演进示例交易结算引擎升级、用户身份认证体系重构、GDPR数据删除流程流程必须召开红灯任务启动会参会者包括主程、安全官、法务代表、领域专家会议产出《红灯任务契约》明确哪些模块允许AI辅助如日志格式化、监控埋点哪些模块禁止AI触碰如签名验签、余额扣减所有AI辅助代码必须加// red-light: assisted-by-claude标记开发过程全程录屏AI交互记录存入审计日志红灯任务不是不用AI而是把AI降级为“高级文本处理器”。比如在写结算引擎时AI可以帮我们把监管文档里的“T1清算”要求转成注释但绝不允许它生成deductBalance()函数。3.3 真实踩坑当“黄灯”被当成“绿灯”处理去年Q3我们有个黄灯任务——重构优惠券发放服务。开发工程师觉得“不就是改个Redis key格式”擅自走绿灯流程。AI生成的代码完美符合CLAUDE.md测试全部通过CI自动合并。上线后第三天风控系统报警同一张优惠券被并发发放了17次。根因分析发现AI生成的getCacheKey()函数用了Date.now()作为key的一部分而服务是集群部署不同节点时间差导致key不一致缓存穿透。这个Bug暴露了AGENTS.md的致命漏洞我们没定义“并发安全”是否属于黄灯任务的强制评审项。补救措施在AGENTS.md#yellow-task-template中新增条款“所有涉及缓存、锁、计数器的操作必须提供并发压测报告≥1000 TPS”在CI流水线增加concurrency-checker插件自动扫描AI生成代码中的Date.now()、Math.random()、new Date()等非幂等操作从此“时间相关操作”成为黄灯任务的默认红区。4.OpenSpec让AI从“猜意图”到“守契约”不是文档是服务契约如果说CLAUDE.md是给AI定岗AGENTS.md是给流程定规那么OpenSpec就是给交付定契——它把模糊的“我要一个用户登录功能”变成机器可读、AI可执行、人类可验证的精确契约。热搜词里反复出现的openspec使用教程、openspec官方文档背后藏着一个残酷真相90%的AI编程失败不是因为模型不行而是因为契约缺失。AI不是人它不会问“你到底想要什么”它只会拼命匹配你提示词里最频繁出现的token。你写“用户登录”它可能生成一个带JWT签发的完整认证服务你写“用户登录界面”它可能只给你一个带表单的React组件。没有契约AI就在猜谜。OpenSpec就是终结猜谜的武器。它不是Swagger的替代品而是Swagger的增强层——在OpenAPI 3.0基础上增加了AI可执行的元数据、质量约束和演化规则。4.1OpenSpec与传统OpenAPI的本质差异维度传统OpenAPI 3.0OpenSpec目标读者人类开发者、前端工程师、测试人员AI代码生成器、CI质量门禁、契约验证引擎核心字段paths,components/schemas,responses新增x-ai-constraints,x-evolution-rules,x-quality-gates验证方式人工阅读、Postman测试自动化扫描openspec-validateCLI、AI生成前校验、CI流水线拦截演化管理版本号递增v1→v2无兼容性声明显式声明breaking-changes: [field_removed, type_changed]AI生成时自动拒绝不兼容变更我们团队的product-api.yaml第一行不再是openapi: 3.0.0而是openapi: 3.0.0 info: title: Product Catalog API version: 2.3.1 x-ai-constraints: # 这些约束会被AI生成器实时读取 response_schema_strictness: strict # 禁止AI返回额外字段 error_handling: standardize # 所有错误必须返回统一Error Schema pagination: cursor_based # 分页必须用cursor禁用offset/limit x-evolution-rules: # 定义API如何安全演进 - rule: adding new optional field is allowed - rule: changing field type from string to number is breaking - rule: removing deprecated field requires 2 versions grace period x-quality-gates: # CI流水线的质量门禁 - gate: response_time_p95 200ms - gate: error_rate 0.1% - gate: security_scan_pass: true当AI要生成GET /products的Service时它首先读取x-ai-constraints就知道返回数据必须严格匹配components/schemas/ProductListResponse不能多也不能少错误响应必须用components/schemas/StandardError不能自己发明{code: 50001, msg: xxx}分页参数必须是?cursorxxxlimit20不能用?page1size20。4.2OpenSpec驱动的AI生成全流程以生成src/services/productService.ts为例整个流程完全由OpenSpec驱动4.2.1 步骤1契约解析AI启动前AI引擎加载src/specs/product-api.yaml执行以下校验检查x-ai-constraints.response_schema_strictness strict→ 启用Schema严格校验模式解析paths[/products][get][responses][200][content][application/json][schema]→ 获取返回类型定义提取x-quality-gates中response_time_p95阈值 → 生成代码时自动注入性能监控埋点4.2.2 步骤2代码生成AI执行中AI根据契约生成TypeScript代码关键特征所有DTO类型直接从OpenAPI Schema生成而非手写// 自动生成非手写 export interface ProductListResponse { data: Array{ id: string; name: string; price: number; tags?: Arraystring; }; next_cursor?: string; }HTTP调用强制使用预设的apiClient已配置超时、重试、监控// 自动生成含性能埋点 export const getProductList async (params: { cursor?: string; limit?: number }) { const start performance.now(); try { const res await apiClient.getProductListResponse(/products, { params }); performance.mark(product-list-success-${Date.now()}); return res.data; } catch (e) { performance.mark(product-list-error-${Date.now()}); throw e; } };错误处理统一// 自动生成符合x-ai-constraints.error_handling if (res.status 400) { const error res.data as StandardError; throw new ApiError(error.code, error.message, error.details); }4.2.3 步骤3契约验证AI交付后生成代码提交前CI流水线运行# 1. 验证代码是否符合OpenSpec契约 openspec-validate --spec src/specs/product-api.yaml --code src/services/productService.ts # 2. 验证生成的测试用例是否覆盖所有2xx/4xx响应 jest --coverage --testPathPatternproductService.test.ts # 3. 静态扫描是否引入不合规依赖 npx eslint --rule no-restricted-imports: [2, {patterns: [axios]}] src/services/productService.ts只有全部通过PR才能进入Validate环节。4.3OpenSpec实战从“没有它”到“有它”的质变我们做过对照实验同一组工程师用相同Claude模型分别处理两个相似需求——组A无OpenSpec需求“获取用户收藏商品列表”提示词“写个API调用函数返回用户收藏的商品”。结果生成了5个版本最终版返回{items: []}但产品实际需要{data: {list: []}, meta: {total: 100}}返工3次。组B有OpenSpec需求指向src/specs/user-favorite-api.yamlAI自动读取paths[/users/{id}/favorites][get][responses][200]。结果首次生成即符合契约返回类型、错误处理、分页参数全部正确测试覆盖率92%。差距不在AI而在契约。OpenSpec把“人话需求”翻译成“机器语言”让AI从“尽力而为”变成“必须履约”。提示OpenSpec不是一劳永逸的文档。我们每周四下午固定1小时做OpenSpec健康度检查扫描所有x-ai-constraints字段确认是否有过期规则如response_schema_strictness: loose已被弃用对比Git历史检查是否有API变更未同步更新x-evolution-rules运行openspec-diff工具生成本周契约变更报告邮件发送给全体工程师这确保OpenSpec始终是活的契约而不是尘封的PDF。5. 三件套协同当CLAUDE.md、AGENTS.md、OpenSpec开始互相咬合单独看CLAUDE.md、AGENTS.md、OpenSpec它们只是三份文档。但当它们开始互相引用、互相校验、互相驱动时AI编程才真正完成从“能用”到“好用”的跃迁。这种协同不是理论设计而是我们在MIT AI编程课程项目中实打实跑出来的闭环。当时要做一个校园二手书交易平台需求是“学生能发布、搜索、购买书籍”团队6人工期4周。没有三件套时我们花了2周在AI生成的代码里修Bug引入三件套后第3天就交付了MVP第7天完成全栈上线。5.1 协同起点OpenSpec驱动CLAUDE.md条款动态更新OpenSpec不是静态文档它是AI生成的源头活水。当API契约变化时CLAUDE.md必须自动适应。我们用openspec-sync工具实现联动当src/specs/book-api.yaml中x-ai-constraints.response_schema_strictness从loose改为strict时工具自动扫描CLAUDE.md找到output_formatting区块将原条款AI生成代码可返回额外字段替换为AI生成代码必须严格匹配OpenSpec定义的Schema禁止返回额外字段并提交PR标题为[AUTO] Update CLAUDE.md to enforce strict schema matching per book-api.yaml v1.4。这个机制让我们避免了“契约已更新但AI还在按旧规则生成”的经典陷阱。过去半年CLAUDE.md的23次更新中17次由OpenSpec变更自动触发。5.2 协同枢纽AGENTS.md用OpenSpec版本号锁定AI生成上下文在AGENTS.md的Initiate环节我们强制要求指令中必须包含OpenSpec版本引用CONTEXT: src/services/bookService.ts | module: book-marketplace | last-commit: feat(book): add wishlist feature TASK: generate wishlist service functions for adding/removing books CONSTRAINTS: - use OpenSpec v1.4 (src/specs/book-api.yaml) - all endpoints must include x-correlation-id header - error responses must match components/schemas/WishlistError这个use OpenSpec v1.4不是装饰而是AI生成器的“上下文锚点”。AI引擎会加载book-api.yamlv1.4版本而非最新版确保生成代码与当前分支契约一致校验x-correlation-id是否在paths[/wishlist][post][parameters]中定义提取WishlistErrorSchema生成对应的TypeScript类型。如果没有这个锚点AI可能加载了v1.5已废弃x-correlation-id生成的代码在CI中直接失败。5.3 协同终点CLAUDE.md条款成为AGENTS.md验证环节的自动化检查项Validate环节的自动化扫描不只是跑测试更是用CLAUDE.md当尺子量AI的交付物。我们开发了claude-linterCLI工具它读取CLAUDE.md中的output_formatting条款并对AI生成代码做静态分析扫描console.log出现次数 → 验证“零注释”条款检查const声明数量与魔法值数量比 → 验证“零魔法值”条款统计any/object类型出现位置 → 验证“强类型优先”条款匹配// scope:标记与CLAUDE.md#role_and_scope→ 验证“工作辖区”条款这个工具集成在CI中任何违反CLAUDE.md的代码都会在Validate环节被拦截错误信息直接指向CLAUDE.md的具体条款编号如CLAUDE.md#2.2.3-3开发者一眼就知道该去改哪条契约。5.4 真实协同案例光大证券股市数据服务的AI交付在光大证券的项目中我们需要快速交付一个“实时行情历史K线交易信号”服务。传统方式需3名后端2名前端1名测试周期6周。我们用三件套协同Step 1架构师用OpenSpec定义market-data-api.yaml明确/quote返回{symbol, price, change_pct}/kline返回{timestamp, open, high, low, close, volume}/signal返回{type: buy|sell, confidence: 0.8}Step 2开发工程师按AGENTS.md黄灯流程编写指令并引用OpenSpec v2.1Step 3AI生成src/services/marketService.tsclaude-linter扫描通过openspec-validate校验通过Step 4QA工程师执行AGENTS.md#Validate重点测试/signal的置信度阈值是否可配置OpenSpec中x-ai-constraints已声明configurable_threshold: trueStep 5主程审核发现/kline返回的volume字段单位应为millions而非units立即更新OpenSpec并触发CLAUDE.md自动同步。整个服务从需求提出到上线耗时11天其中AI生成代码仅用27分钟。关键不是AI快而是三件套让每一次生成都精准命中契约每一次验证都有据可依每一次迭代都闭环可控。6. 工程化落地的硬核检查清单别让AI编程死在第一步我知道看到这里你可能已经打开编辑器想写CLAUDE.md了。但请先停一下——我见过太多团队倒在第一步文档写得漂亮但没人用、没人审、没人更新最后变成项目根目录下最孤独的Markdown文件。工程化不是写文档是建机制。下面这份检查清单是我们团队踩坑后提炼的“生存指南”每一条都对应一个真实翻车现场6.1 文档即代码CLAUDE.md必须通过CI流水线校验必须做在CI中添加步骤运行markdownlint CLAUDE.md禁止header-increment标题跳级、no-multiple-blanks多余空行、fenced-code-language代码块缺失语言标识必须做用正则扫描CLAUDE.md中的TODO、FIXME、XXX发现即失败——文档里不能有“待办事项”只有“已决议项”必须做git diff检测CLAUDE.md变更若新增role_and_scope条款必须关联Jira需求ID如PROJ-1234否则CI拒绝合并。我们曾因CLAUDE.md里一个// TODO: add security rules注释导致CI流水线阻塞3小时。现在所有条款都必须是“已完成”状态。6.2 权限即契约AGENTS.md的每个角色必须有明确Owner必须做在AGENTS.md顶部声明owners区块指定Initiate、Validate、Integrate环节的负责人姓名/工号每月更新必须做Validate环节的QA工程师必须有openspec-validate工具的执行权限且其账号绑定到CI流水线必须做Integrate环节的主程必须拥有OpenSpec仓库的write权限确保契约更新与代码合并同步。曾有团队把AGENTS.md写成“理想流程”结果Validate环节没人认领AI生成的代码直接进主干。现在每个环节Owner的名字都加粗显示且链接到企业微信个人主页。6.3 契约即资产