1. 项目概述从“人治”到“法治”的AI协作革命如果你和我一样已经深度使用Cursor、Copilot这类AI编程工具超过一年你肯定经历过这样的场景今天让AI生成一个React组件它写得规规矩矩明天换个问法或者换了个团队成员来操作生成的代码风格就变得五花八门。更头疼的是当你要开发一个微信小程序页面时你得一遍又一遍地告诉AI“我们这里用Page({})定义页面数据放data里方法放methods里……” 这些重复的、项目特定的“上下文”沟通消耗了大量本应用于创造性思考的时间。ADRAI Development Runtime正是为了解决这个核心痛点而生的。它不是一个新AI工具而是一个工具无关的AI协作运行时框架其核心思想是把团队的开发经验、项目规范和工作流程从依赖个人“Prompt口才”的“人治”状态转变为用文件固化、版本可控的“法治”体系。简单来说ADR为你和你的团队构建了一个“AI副驾驶”的标准化操作手册。无论团队里谁、用哪款AI工具Cursor, Trae, Copilot, Claude等只要遵循这个手册就能输出风格统一、符合项目规范的高质量代码。它特别适合技术负责人、架构师以及追求工程效率的敏捷团队旨在将AI从“个人玩具”升级为“团队生产力引擎”。接下来我将结合自己搭建和落地ADR的实战经验为你彻底拆解它的设计哲学、实操细节以及那些只有踩过坑才知道的注意事项。2. 核心架构与设计哲学拆解2.1 为什么是“运行时”而非“插件”很多初次接触ADR的开发者会疑惑这看起来不就是一套模板和规则文件吗为什么叫“运行时”理解这一点至关重要。传统的IDE插件或工具扩展是深度绑定在特定工具生态内的。比如一个为Cursor写的插件无法直接在GitHub Copilot Chat里使用。而ADR的“运行时”理念是将规则层与应用层解耦。你可以把ADR框架想象成一套独立的“交通法规”和“城市地图”规则与上下文而Cursor、Copilot等AI工具则是不同品牌的“汽车”。无论你开什么车在这套法规和地图的指引下都能到达正确的地点且驾驶行为是规范的。这种设计带来了几个关键优势首先它避免了厂商锁定团队不会因为依赖某个AI工具而丧失灵活性。其次它使得团队的知识资产得以独立沉淀所有规则都以Markdown文件形式存在可以用Git进行版本管理和协作演进即使未来AI工具迭代或更换这套核心资产依然有效。2.2 三层架构从通用到具体的知识封装ADR的目录结构清晰地体现了其分层治理的思想这是保证其扩展性和复用性的关键。第一层平台模板库 (platforms/)这是最通用的一层面向技术栈。例如platforms/miniprogram/目录下存放所有微信小程序开发的通用约定页面生命周期函数怎么写、WXML模板的基本结构、WXSS的命名空间如何避免污染等。当你的项目是一个小程序时就会自动继承和应用这层的规则。这相当于为AI预先装载了“小程序开发”的领域知识避免了每次都要从零开始教学。第二层项目上下文库 (projects/)这是中间层面向具体项目。每个使用ADR的项目都会在这里拥有一个独立的文件夹例如projects/FlashCalcLifeWxApp/。这里面存放的是该项目独一无二的“记忆”和“规范”主要包含两个文件README.md: 项目简介、技术栈、目录结构说明、核心业务逻辑描述。这是AI了解项目全貌的入口。coding.md: 项目专属的开发规范。它继承并细化了平台层的通用规范。比如在通用小程序规范基础上本项目可能规定所有API请求必须使用封装在utils/request.js中的方法所有组件命名必须以Fcl前缀开头。第三层工作区 (Workspace)这就是你的实际项目代码目录比如/Users/yourname/Developer/MyApp。在这里你通过ADR CLI工具或AI工具的入口指令驱动AI基于上述两层规则进行编码。工作区本身不存放规则只产生符合规则的代码输出。这种架构的精妙之处在于关注点分离和继承机制。平台工程师维护platforms/确保技术栈最佳实践项目负责人维护projects/下的对应目录定义业务约束而普通开发者只需在工作区专注业务逻辑实现。AI作为执行者无缝地融合了这三层知识。2.3 工作流驱动固化团队协作的“SOP”ADR定义了三个核心工作流/init,/feature,/fix。这不仅仅是三个命令更是将团队开发流程标准化的关键。/init: 项目初始化工作流。它不是一个简单的脚手架而是一个上下文发现与创建的过程。当你在一个已有或全新的项目目录下执行adr initADR CLI会分析项目结构如是否存在app.json,package.json识别项目类型然后在projects/下生成对应的项目上下文文件夹和基础文件。开发者随后需要去完善这些文件这个过程本身就是一次对项目规范的梳理和共识达成。/feature: 功能开发工作流。开发者输入/feature 实现用户登录模块包含手机号验证码登录AI会依据项目上下文和平台模板生成从页面、组件到逻辑的完整代码并且自动遵循命名规范、代码结构等所有约定。这极大地减少了“这个页面该怎么组织”、“接口该怎么调用”之类的低级沟通。/fix: 问题修复工作流。输入/fix 修复首页数据偶尔不加载的问题AI会结合错误日志如果提供、代码上下文并依据策略库中的“变更边界”原则如优先进行最小化修复避免影响无关功能给出修复方案。实操心得不要小看这三个简单的工作流。在团队内强制推行使用它们能显著减少代码评审时的风格争议让评审者更专注于业务逻辑和架构设计而不是纠结于缩进或命名。这相当于为团队建立了人机协作的“标准作业程序”。3. 从零开始部署与配置ADR3.1 环境准备与框架获取首先你需要获取ADR框架本身。它是一个开源仓库通常通过Git克隆到本地一个中心位置供所有项目引用。# 选择一个你常用的开发目录克隆ADR仓库 git clone https://github.com/Stephenxu000/adr-runtime.git ~/Developer/adr cd ~/Developer/adr这个~/Developer/adr目录将成为你的“ADR中心库”。所有共享的规则、模板都将存放在这里。接下来你需要确保系统安装了Node.js因为ADR CLI工具基于Node然后安装其命令行工具。# 进入ADR框架的cli包目录 cd packages/cli # 进行全局链接或本地安装推荐全局链接方便在任何项目使用 npm link # 或者使用 npm install -g . 进行全局安装安装完成后在终端输入adr --help应该能看到命令帮助信息确认CLI工具可用。3.2 配置你的AI工具建立连接通道这是让ADR规则生效的关键一步。你需要将ADR的“团队入口”文件链接到你使用的AI工具所能识别的规则文件位置。这个入口文件 (runtime/team_entry.md) 定义了AI的核心角色、约束和如何查找其他规则。针对不同工具的配置方法配置 Cursor: Cursor 会读取项目根目录下的.cursorrules文件作为规则。我们只需要将ADR的入口文件软链接或复制过去。我强烈建议使用软链接这样当中心库的规则更新时所有项目能自动同步。# 在你的项目根目录下执行例如 ~/Developer/MyProject ln -s ~/Developer/adr/runtime/team_entry.md .cursorrules这样当你在该项目中使用Cursor时它就会加载ADR的整套规则。配置 GitHub Copilot (Chat): Copilot Chat 在仓库中会读取.github/copilot-instructions.md文件。同样使用软链接。# 在你的项目根目录下 mkdir -p .github ln -s ~/Developer/adr/runtime/team_entry.md .github/copilot-instructions.md配置 Trae: Trae 的规则文件通常在.trae/project_rules.md。# 在你的项目根目录下 mkdir -p .trae ln -s ~/Developer/adr/runtime/team_entry.md .trae/project_rules.md重要注意事项使用cp命令复制文件虽然简单但会导致副本独立后续中心库更新时需要手动同步容易产生规则不一致。在生产团队中务必使用ln -s创建符号链接确保单一事实来源。唯一的例外是如果你的项目需要被部署到一个无法访问你本地中心库路径的环境如某些CI/CD容器则可以考虑在构建脚本中加入复制步骤。3.3 初始化你的第一个项目假设我们有一个已存在的微信小程序项目FlashCalcLifeWxApp位于~/Developer/FlashCalcLifeWxApp。# 1. 进入你的项目目录 cd ~/Developer/FlashCalcLifeWxApp # 2. 执行ADR初始化并指定生成中文上下文--lang zh adr init --lang zh # 3. 观察输出。CLI工具会 # a. 扫描当前目录识别出是一个微信小程序项目通过app.json等文件。 # b. 在ADR中心库的 projects/ 目录下创建 FlashCalcLifeWxApp 文件夹。 # c. 根据 platforms/miniprogram/ 的模板生成初始的 README.md 和 coding.md 文件。 # d. 提示你“项目上下文已生成请前往 ~/Developer/adr/projects/FlashCalcLifeWxApp/ 进行review和完善。” # 4. 完善项目上下文 # 这是最关键的一步直接决定后续AI协作的质量。 # 用你喜欢的编辑器打开生成的两个文件填充真实信息。完善projects/FlashCalcLifeWxApp/README.md示例# FlashCalcLifeWxApp (秒算生活) ## 项目信息 - **项目类型**: WeChat Mini Program - **主要语言**: JavaScript WXML WXSS - **项目状态**: 生产环境 V1.2.0 - **代码仓库**: https://git.company.com/fe/flash-calc-life ## 技术栈 - 微信小程序原生框架 - 使用 Vant Weapp 组件库 (版本: 1.10.0) - 使用 wx.request 封装的网络层 /utils/http - 状态管理使用小程序自带的 app.globalData 结合页面模块化存储 ## 项目结构FlashCalcLifeWxApp/ ├── app.js / app.json / app.wxss # 全局文件 ├── pages/ # 页面目录 │ ├── index/ # 首页 │ ├── calculator/ # 计算器页 │ └── profile/ # 个人中心 ├── components/ # 公共组件 │ ├── fcl-button/ # 统一按钮组件 │ └── fcl-loading/ # 加载状态组件 ├── utils/ # 工具函数 │ ├── http.js # 网络请求封装 │ ├── validator.js # 表单验证 │ └── format.js # 数据格式化 └── config/ # 配置文件 └── env.js # 环境配置## 项目描述 **秒算生活**是一款面向年轻用户的轻量化生活计算工具小程序。核心功能包括房贷计算器、个税计算器、日常开销统计等。设计风格为简约清新强调单次计算的即时性和结果可视化。 ## 核心业务逻辑约定 1. 所有页面跳转使用 wx.navigateTo返回使用 wx.navigateBack。 2. 用户登录态通过 app.globalData.userInfo 管理过期自动跳转至登录页。 3. 所有异步计算操作必须显示 fcl-loading 组件。 ## 相关文档 - [开发规范](./coding.md) - 项目特定的开发规范 - [API接口文档](https://docs.company.com/api/miniprogram) - 后端接口Swagger地址完善projects/FlashCalcLifeWxApp/coding.md示例# FlashCalcLifeWxApp - 开发规范 本文件定义项目特定的开发规范继承并扩展ADR框架的通用规范。 ## 命名约定 ### 文件命名 - 页面目录pages/xxx**kebab-case** (如 loan-calculator) - 组件目录components/xxx**kebab-case**且以 fcl- 前缀开头 (如 fcl-result-card) - JavaScript 文件**camelCase.js** (如 formatNumber.js) - WXML/WXSS 文件与目录同名**kebab-case** ### 变量与函数命名 - 使用 **camelCase** - 布尔变量以 is, has, can 开头 (如 isLoading, hasUserInfo) - 异步函数名以 fetch, load, submit 等动词开头或使用 async 后缀明确标识 (如 fetchUserData) ## 代码结构规范 ### 页面 (Page) 结构顺序 1. data 对象 2. onLoad, onShow 等生命周期函数 3. 事件处理函数 (以 on 或 handle 开头如 onButtonTap) 4. 自定义方法 5. onShareAppMessage 等微信特定函数 ### 组件 (Component) 结构 - 必须包含 properties, data, methods, lifetimes 等标准字段。 - 外部传入的属性 (properties) 需在注释中说明类型和用途。 ## 项目特定API规范 - **所有网络请求**必须通过 /utils/http 模块的 request 函数发起。 - 请求URL统一在 config/env.js 中配置根据环境变量切换。 - 请求成功/失败需统一使用项目封装的 showToast 或 showModal 方法进行用户反馈。 ## 样式 (WXSS) 规范 - 页面样式使用 page 作为根选择器。 - 组件样式使用自定义组件名作为命名空间避免样式污染。 - 颜色、字体大小等使用在 app.wxss 中定义的CSS变量如 var(--primary-color)。 ## 提交信息规范 - 遵循 Conventional Commits格式type(scope): subject - 例如feat(calculator): 新增等额本息还款计算功能完成以上编辑后你的ADR框架就为这个项目准备好了完整的“知识库”。接下来就可以体验AI驱动的标准化开发了。4. 核心工作流实战与技巧4.1/feature工作流高效的功能开发假设我们需要在“秒算生活”小程序中新增一个“汇率计算器”页面。传统方式你需要向AI描述这是一个微信小程序页面需要放在pages/目录下页面结构包括标题、货币选择下拉框、金额输入框、转换按钮和结果展示区域。还要说明用哪个组件库、网络请求怎么调用、数据格式是什么……可能需要多轮对话才能得到满意的代码。使用ADR后你只需要在AI聊天框中输入/feature 新增一个汇率计算器页面功能包括两种货币选择下拉框、金额输入、实时汇率获取调用某API、计算转换结果并展示。页面命名为 exchange-rate。AI会执行以下自动化流程读取角色与约束首先加载runtime/team_entry.md知道自己是遵循ADR规则的助手。定位项目上下文根据当前工作目录找到projects/FlashCalcLifeWxApp/下的README.md和coding.md。应用平台模板识别为小程序项目应用platforms/miniprogram/page_template.md中的页面基础模板。遵循编码策略参考policies/coding_policy.md中的通用代码规范如错误处理、注释要求。生成最终代码综合以上所有信息生成一个完全符合项目规范的页面。它会在pages/下创建exchange-rate目录kebab-case命名。生成exchange-rate.js其中data包含fromCurrency,toCurrency,amount,rate,result等字段生命周期函数和事件处理函数顺序符合规范。生成exchange-rate.wxml使用Vant Weapp的van-dropdown-menu,van-field等组件因为README.md声明了使用该库。生成exchange-rate.wxss样式使用CSS变量。在exchange-rate.js的onLoad中使用/utils/http.request()来获取初始汇率符合coding.md的API规范。所有函数命名、变量命名都遵循coding.md中的约定。生成代码示例片段 (exchange-rate.js)// pages/exchange-rate/exchange-rate.js Page({ /** * 页面初始数据 */ data: { // 货币列表 currencyList: [CNY, USD, EUR, JPY], // 源货币 fromCurrency: CNY, // 目标货币 toCurrency: USD, // 输入金额 amount: , // 当前汇率 currentRate: null, // 计算结果 calculatedResult: null, // 加载状态 isLoading: false, }, /** * 生命周期函数--监听页面加载 */ onLoad(options) { this.fetchExchangeRate(this.data.fromCurrency, this.data.toCurrency); }, /** * 获取实时汇率 * param {string} from - 源货币代码 * param {string} to - 目标货币代码 */ async fetchExchangeRate(from, to) { // 遵循项目规范设置加载状态 this.setData({ isLoading: true }); try { // 遵循项目规范使用封装的http模块URL从config读取 const response await getApp().globalData.http.request({ url: getApp().globalData.config.api.exchangeRate, method: GET, data: { from, to } }); this.setData({ currentRate: response.data.rate, isLoading: false }); // 如果已有输入金额则立即计算 if (this.data.amount) { this.calculateResult(); } } catch (error) { this.setData({ isLoading: false }); // 遵循项目规范使用统一反馈 getApp().globalData.utils.showToast(汇率获取失败); console.error(Fetch exchange rate error:, error); } }, /** * 处理货币选择变化 */ onFromCurrencyChange(event) { const newCurrency event.detail; this.setData({ fromCurrency: newCurrency }); this.fetchExchangeRate(newCurrency, this.data.toCurrency); }, // ... 其他事件处理函数如 onToCurrencyChange, onAmountInput, calculateResult 等 });你可以看到生成的代码不仅功能完整而且深度嵌入了项目特定的约定如全局的http对象、showToast方法、isLoading状态命名等。这极大地提升了代码的一致性和可维护性。4.2/fix工作流精准的问题定位与修复当测试报告“汇率计算器页面在iOS设备上下拉框选择后页面偶尔卡死”时传统方式可能需要开发者手动复现、断点调试、猜测可能原因是否是数据更新问题、是否是组件库兼容性问题等。使用ADR的/fix工作流你可以提供更丰富的上下文/fix 汇率计算器页面pages/exchange-rate在iOS设备上当用户切换货币下拉框后页面有概率停止响应。错误可能出现在 onCurrencyChange 事件处理或 setData 更新过程中。请优先检查Vant Weapp下拉框组件在小程序iOS端的兼容性问题。AI会如何工作分析上下文它首先会定位到pages/exchange-rate/exchange-rate.js文件。应用策略参考policies/下的策略例如change_boundaries.md中可能强调“优先进行最小化修复”、“避免重构无关代码”。结合知识读取projects/FlashCalcLifeWxApp/README.md知道项目使用了Vant Weapp v1.10.0。推理与修复基于常见问题模式它可能会检查onCurrencyChange事件中是否有耗时的同步操作阻塞了UI线程。建议将setData调用包裹在wx.nextTick中以确保在正确时机更新。查阅Vant Weapp的Issue历史如果其知识库包含提出已知的iOS兼容性补丁例如建议给下拉菜单组件添加特定的CSS属性-webkit-overflow-scrolling: touch以改善滚动性能。最终它可能给出一个具体的代码修改建议并解释修改原因。避坑技巧为了让/fix更有效在提交问题描述时尽量提供“症状”、“触发条件”、“相关代码文件”和“你的初步怀疑”。这能帮助AI更精准地模拟一个有经验的开发者的排查思路。同时务必在coding.md或team_memory.md中记录下已验证的解决方案形成团队知识沉淀。4.3/init工作流的进阶使用迁移与重构/init不仅用于全新项目。在以下场景中它同样威力巨大项目迁移将一个老旧项目接入ADR体系。执行adr init生成基础上下文后你可以将老项目中的一些隐性规范比如“我们习惯把工具函数都放在lib/下”显式地写入coding.md为后续的AI协作和新人上手铺平道路。技术栈升级比如从原生小程序迁移到Uni-app。你可以先手动更新platforms/下的模板然后在项目中重新运行adr init可能需要一些参数或手动调整让项目上下文与新的平台模板对齐。多仓库管理对于微前端或模块化仓库你可以在每个子仓库中分别运行adr init并让它们的coding.md继承自一个共用的“父级”项目上下文实现规范的统一管理和差异化定制。5. 规则与模板的深度定制指南5.1 编写高效的team_entry.md团队入口这个文件是AI的“总指挥”。一个优秀的入口文件应该清晰定义AI的角色、边界和工作模式。# ADR 团队协作规则 ## 你的角色 你是我们开发团队的一名**高级全栈工程师**精通当前项目所使用的技术栈。你的任务是遵循团队已固化的开发规范和上下文高效、准确地完成代码开发、问题修复和方案设计。 ## 核心工作原则 1. **上下文驱动**在开始任何任务前必须首先读取并理解当前项目的上下文projects/项目名/ 下的文件。 2. **规范优先**所有输出必须严格遵守项目 coding.md 和共享 policies/ 中定义的规范。 3. **模板化生成**对于常见任务如创建页面、组件优先使用 platforms/ 下对应的模板。 4. **最小化变更**修复问题时优先定位根本原因并做最小范围的修改避免引入不必要的变更。 ## 工作流指令 当用户使用以下指令时请按对应流程工作 - /init: 引导用户或自动执行项目初始化流程。 - /feature [描述]: 执行功能开发流程。基于项目上下文和平台模板生成完整、可运行的代码。 - /fix [描述]: 执行问题修复流程。分析问题定位原因提供最小化修复方案。 ## 输出契约 - **代码**必须是完整、可运行、符合ESLint配置如果存在的。 - **解释**在提供代码块后用简短文字说明关键逻辑和设计考量。 - **未知**如果遇到项目上下文中未定义的规范或模糊需求主动提问澄清而不是猜测。经验之谈在team_entry.md中强调“主动提问”非常重要。这能防止AI在信息不足时胡编乱造。同时明确“最小化变更”原则可以避免AI在修复一个简单bug时顺手“优化”掉一大片无关代码导致代码评审复杂化。5.2 设计可复用的平台模板 (platforms/)平台模板是技术栈知识的结晶。以platforms/miniprogram/page_template.md为例它不应该只是一个代码骨架而应该包含最佳实践和设计模式。# 微信小程序 - 页面模板 ## 设计理念 本模板遵循微信小程序官方最佳实践并融入了常见的状态管理和性能优化模式。 ## 标准页面结构 (Page) javascript // pages/example/example.js Page({ // 1. DATA - 页面数据 data: { // 状态数据 isLoading: false, hasError: false, errorMsg: , // 业务数据 list: [], currentPage: 1, total: 0, // 表单数据 form: { name: , value: } }, // 2. LIFECYCLE - 生命周期按顺序 onLoad(query) { // 接收页面参数初始化数据 this.initData(query); }, onShow() { // 页面显示时可刷新数据 if (this.data.needRefresh) { this.loadData(); } }, onReady() {}, onHide() {}, onUnload() {}, // 3. EVENT HANDLERS - 事件处理以on或handle开头 onButtonTap(e) { const { id } e.currentTarget.dataset; this.handleAction(id); }, onInputChange(e) { const { field } e.currentTarget.dataset; const { value } e.detail; this.setData({ [form.${field}]: value }); }, // 4. CUSTOM METHODS - 自定义方法按功能模块分组 // 数据加载相关 async loadData() { if (this.data.isLoading) return; this.setData({ isLoading: true }); try { const result await this.fetchApi(); this.setData({ list: result.list, total: result.total, isLoading: false, hasError: false }); } catch (error) { this.setData({ isLoading: false, hasError: true, errorMsg: error.message }); } }, // 工具方法 showToast(title, icon none) { wx.showToast({ title, icon }); }, // 5. PAGE EVENT - 页面事件如分享、下拉刷新等 onPullDownRefresh() { this.refreshData().finally(() wx.stopPullDownRefresh()); }, onShareAppMessage() { return { title: 分享标题, path: /pages/example/example }; } });关键约定数据扁平化避免过深的data嵌套以提升setData性能。异步处理所有网络请求必须使用async/await或Promise并妥善处理加载和错误状态。事件命名采用onXxx或handleXxx格式明确表示这是对用户交互的响应。方法组织将相关功能的方法放在一起并用空行和注释分隔不同模块。### 5.3 维护团队记忆 (context/team_memory.md) 这是ADR框架中最具“人性化”和“成长性”的部分。它用于记录那些无法简单归入规范或模板但对团队效率至关重要的**经验、决策和坑点**。 markdown # 团队记忆与经验库 ## 性能优化记录 - **2024-01-15**: 发现小程序中频繁调用 setData 且数据量较大时iOS端会出现明显卡顿。**解决方案**对列表数据采用分片更新或使用 wx.nextTick 延迟非关键UI更新。 - **2023-12-10**: Vant Weapp 的 van-popup 组件在嵌套滚动区域中在Android机上有触摸穿透问题。**解决方案**为 van-popup 添加 catch:touchmove 事件阻止默认行为。 ## 第三方库集成备忘 - **图表库 F2**: 需要在页面 onReady 后初始化图表实例并在 onUnload 中手动销毁防止内存泄漏。 - **地图组件 map**: 使用自定义图层时需注意 cover-view 的层级问题建议使用 markers 或 callout 实现交互。 ## 业务逻辑模式 - **用户登录态校验**: 封装成 requireAuth 高阶函数在页面 onLoad 中调用统一处理登录跳转逻辑。 - **表单提交防重**: 使用 this.data.isSubmitting 标志位在提交开始时置为 true结束时置为 false并在按钮上绑定 disabled 属性。 ## 已废弃的实践 - ~~使用 wx:for 嵌套过深超过3层渲染长列表会导致初始化白屏时间过长。已改用 wx:for 配合 wx:if 分块渲染。~~定期维护这个文件相当于在为团队的“AI副驾驶”进行持续训练让它变得越来越懂你们的项目和团队习惯。6. 团队协作、版本管理与进阶实践6.1 将ADR集成到团队工作流要让ADR在团队中真正发挥作用需要将其融入现有的开发流程。中心库版本化将~/Developer/adr这个ADR框架目录本身作为一个Git仓库进行管理。platforms/、policies/、workflows/的修改需要经过Pull Request和代码评审确保规则变更被充分讨论。项目上下文同步每个项目的projects/项目名/目录其变更也应该纳入该项目的版本控制。当项目规范更新时修改coding.md并提交团队其他成员通过拉取更新即可同步。新人 onboarding新成员入职时只需做三件事a) 克隆项目代码b) 克隆ADR中心库并全局链接CLIc) 在项目目录下运行adr init并配置AI工具。他/她立刻就能获得与老成员一致的AI协作能力极大降低学习成本。Code Review 聚焦由于代码风格和基础规范已由ADR保证评审者可以更专注于业务逻辑的合理性、架构设计的优劣以及性能安全等更深层次的问题。6.2 处理多技术栈与混合项目对于使用多种技术的项目例如一个Taro跨端项目同时输出小程序和H5ADR可以通过灵活的上下文设计来应对。方案一主平台扩展在platforms/下创建taro模板作为主平台。在项目的coding.md中通过章节区分小程序特有的规范和H5特有的规范。方案二多上下文支持可以扩展ADR CLI使其支持adr init --platform taro-miniprogram和adr init --platform taro-h5生成侧重点不同的上下文文件。这需要一定的框架定制能力。6.3 监控与持续改进ADR的落地不是一劳永逸的。需要建立反馈机制收集“坏味道”在Code Review或日常开发中如果发现AI反复犯同一类错误例如总是忘记处理某个边界条件不要仅仅修改代码而应该思考这个错误模式能否通过更新policies/coding_policy.md或platforms/下的模板来从根本上避免定期回顾规则每个季度团队可以花一点时间回顾team_memory.md和coding.md将重复出现的经验沉淀为正式规则将过时的规则进行归档或删除。度量效率提升可以简单记录采用ADR前后完成一个标准功能模块所需的平均沟通轮次和开发时间。这些数据能直观地展示ADR的价值并驱动进一步的优化。7. 常见问题、排查与避坑实录在实际推广和使用ADR的过程中我遇到了不少典型问题。这里汇总一份速查表希望能帮你绕过这些坑。问题现象可能原因解决方案AI完全忽略ADR规则自由发挥。1. AI工具规则文件路径配置错误。2.team_entry.md中的指令格式不被当前AI工具识别。1.检查软链接确认.cursorrules等文件是有效的符号链接且指向正确的ADR中心库路径。使用ls -la查看。2.验证AI工具在AI聊天框中直接问“你现在遵循的规则文件是什么” 检查其回答的路径是否正确。3.简化入口某些AI工具对复杂Markdown解析不佳。尝试简化team_entry.md的格式使用更直接的指令语句。AI生成的代码符合通用规范但不符合我项目的特殊约定如特定的API封装方式。项目的coding.md文件内容不完整或未更新AI缺乏项目特定知识。1.完善coding.md这是最重要的步骤。必须将项目的所有特殊约定工具函数路径、组件库版本、业务逻辑模式清晰写入。2.使用绝对路径引用在coding.md中使用/utils/http这样的别名时确保在README.md中说明了别名配置如Webpack/Vite配置。或者直接写相对路径../../utils/http.js。/feature生成的代码运行时报错比如找不到模块。1. AI引用了项目中不存在的模块或错误版本。2. 平台模板 (platforms/) 中的依赖声明与实际项目不符。1.检查README.md确保其中声明的依赖库和版本号是准确的。AI会依赖这些信息。2.提供更精确的指令在/feature指令中明确指定版本如“使用Vant Weapp v1.10.0的van-field组件”。3.在team_memory.md中记录将此类“幻觉”问题记录下来提醒团队成员在指令中需额外明确。运行adr init时CLI未能正确识别项目类型。CLI的类型识别逻辑基于文件特征如package.json,app.json,vue.config.js等。你的项目可能缺少这些标志性文件或结构非常规。1.手动指定类型查看adr init --help是否有手动指定项目类型的参数如--type miniprogram。2.修改CLI逻辑如果你熟悉Node.js可以修改packages/cli中的项目检测逻辑增加对你项目结构的识别。3.手动创建上下文最直接的方式是在projects/下手动创建项目文件夹和README.md、coding.md文件。团队中有人更新了中心库规则但我本地项目没有生效。你项目中的规则文件如.cursorrules是复制 (cp) 的副本而非软链接 (ln -s)。统一使用软链接这是最重要的最佳实践。要求团队所有成员在初始化项目时必须使用ln -s命令创建符号链接确保规则源头唯一。可以编写一个简单的安装脚本来自动化这个过程。AI在修复问题时进行了不必要的重构改动范围很大。team_entry.md中“最小化变更”原则强调不够或者AI对“修复”和“重构”的边界理解模糊。1.强化原则在team_entry.md的“输出契约”或“工作原则”部分用加粗强调“修复问题时必须首先定位根本原因并提交最小范围的代码变更。除非明确要求否则禁止重构无关代码。”2.细化指令在/fix指令中明确范围例如“/fix 仅修复首页列表加载失败的问题不要修改其他页面的样式”。最重要的一个心得ADR不是“自动驾驶”而是“定速巡航”。它不能替代开发者的思考和设计它的价值在于接管那些重复、琐碎、易出错的规范性工作让开发者能更专注于创造性的逻辑和架构。初期需要投入时间精心设计和维护规则但这个投入会随着项目规模和团队人数的增长带来指数级的回报。从第一个项目开始用起来在用的过程中迭代你的规则库你会发现人机协作的边界正在被重新定义。