用 Cursor / Claude Code 改微前端 monorepo最怕两件事AI没读项目结构在子应用里又装一份 React → Hooks 全炸AI凭感觉改排班冲突校验跳了、401 不跳 SSO 了上线才被发现我现在的解法根目录放一份 CLAUDE.md或 AGENTS.md当 Agent 的「上班第一站」。不是把文档堆给 AI而是告诉它先看哪、别碰啥、怎么加载更多上下文。 CLAUDE.md 是啥不是 README 复制粘贴README 给人类看怎么 install、怎么 dev。CLAUDE.md 给 Agent 看这仓库是什么架构微前端几个子应用关键约束 TOP 5别打包 React、别绕过 SSO……docs/里 harness / knowledge / specs 怎么按需读新需求要不要先走 propose 流程可以把它想成新同事入职第一天你口头交代的那 10 分钟只不过写进文件里AI 每次任务都会读。 微前端项目 CLAUDE.md 建议结构1. 项目概述一张表就够 2. 目录导航docs 树状图标注「唯一索引」 3. 关键约束速览5 条带编号 ARCH-xx / BR-xx / SEC-xx 4. 常用命令openharness / npm scripts 5. Agent 工作规则加载协议、禁止捏造、brownfield 评审基准别写50 页架构史、每个组件 props 说明——那是 knowledge不是入口。 第一节项目概述表Agent 需要先建立「世界观」项目内容架构qiankun 基座 N 个子应用 monorepo框架React 16 各子应用状态库可能不同请求REST GraphQL 混用特点子应用禁止私自打包 Reactexternals 从 window 取一张表30 秒读完后面改 webpack 时 AI 会想起 ARCH-01。️ 第二节目录导航指到 index别指到大海docs/ ├── harness/ ← 约束必须遵守 │ └── index.md ← 先读这个再按「加载时机」读叶子 ├── knowledge/ ← 系统现状怎么运行的 │ └── index.md └── specs/active/ ← 进行中的需求关键句「不得跳过 index 直接凭经验推断。」AI 最爱跳过 index 幻觉出一份「标准微前端」—— 和你仓库里 qiankun 2.x registerGlobal 那套往往对不上。⚡ 第三节关键约束速览只放 TOP 5入口文件只摘最重要的每条一行带编号方便引用ARCH-01— 子应用禁止打包独立 React走 webpack externals 基座 window 注入BR-01— 创建前排班冲突校验后端说冲突就不能放行提交BR-03— 调度指令下发后要轮询结果禁止「点了就成功」SEC-01— 401 / sso_unauthorized 必须跳 SSO子应用别自己搞一套登录BR-06— 锁定状态下编辑/删除按钮必须 disabled别直连接口碰运气完整 12 条 BR、9 条 ARCH 在docs/harness/入口只当菜单不当百科全书。 第五节Agent 工作规则这是灵魂我一般会写 6 条直接抄思路改你们项目1. 任务开始前读 CLAUDE.mdobvious但写了 AI 才真当 mandatory。2. harness 按需加载先docs/harness/index.md看「加载时机」列——改 webpack 才读 architecture改排班才读 invariants/biz。同一会话读过的文件记时间戳别重复灌上下文。3. knowledge 按需加载先docs/knowledge/index.md再决定读 architecture / api / domain-model。禁止没读 knowledge 就开始「我建议你新建一个 Zustand 全局 store」—— 你项目可能全是 Recoil。4. 不确定就问别捏造接口字段、权限码、后端是否已支持——猜错了 merge 进去就是 production bug。5. 新需求走 propose → spec → design → tasksbrownfield 别上来就改代码先文档对齐尤其微前端要评估子应用注册、externals、路由 activeRule。6. brownfield 评审基准兼容性 炫技。新功能默认不动基座 inject 列表除非 index 里写了要动。 CLAUDE.md 和 .cursor/rules 分工文件放啥谁读CLAUDE.md项目地图 docs 协议 TOP 约束Claude Code / 部分 Agent.cursor/rules/*.mdcAlways-on 短规则写法、最小改动Cursor 每轮注入docs/harness/完整 ARCH / BR 条文按需加载docs/knowledge/系统现状按需加载CLAUDE.md 别超过 150 行。长了 AI 也 skim还不如精简 链到 harness。✍️ 微前端专属入口里务必强调的 3 句话写进 CLAUDE.md 或 alwaysApply rule改packages/main或 webpack externals 前先读docs/harness/architecture/microfrontend.md。子应用之间禁止互相 import通信走 qiankun props / initGlobalState。动 service 层前确认 401 处理走基座统一拦截别在子应用 axios 里另起炉灶。这三句能挡掉一半「AI 把 monorepo 当单体改」的事故。 最小可抄模板脱敏版# XXX 微前端 — Agent 工作入口 ## 项目概述 | 架构 | qiankun 基座 N 子应用 monorepo | | 框架 | React 16状态库因应用而异 | ## 目录导航 - docs/harness/index.md — 约束按需读叶子 - docs/knowledge/index.md — 现状按需读叶子 - docs/specs/active/ — 进行中需求 ## 关键约束速览 - ARCH-01子应用 React 必须 externals禁止双实例 - SEC-01401 必须跳 SSO - 再列 3 条你们最常破的 ## Agent 工作规则 1. 任务开始读本文 2. harness / knowledge 按 index 加载时机读不跳过 index 3. 不确定就问不捏造 4. 新需求先 spec/design再写代码 5. brownfield兼容性优先评估对子应用注册的影响复制回去把表格填实第一天就能用。️ 我见过的坑CLAUDE.md 写成第二份 README→ Agent 还是不会读 harness约束写 30 条在入口→ 没有一条被遵守应该 TOP 5 链接没有「加载时机」→ AI 每次全读 harness上下文爆掉开始胡编只给 Claude 不给 Cursor→.cursor/rules补 always-on 的短规则最小改动、别用 — 写博客那是另一回事 最后微前端 AI 协作CLAUDE.md 是门牌号harness 是规定knowledge 是地图。