jerrylususu/ds-reasoner.md

## ds-reasoner.md

      
    Raw
  

              ds-reasoner.md
            
          
    根据您提供的社区讨论，我深入分析了在大型 monorepo 中管理 AI 助手（Claude Code、Cursor、GitHub Copilot 等）配置与规则文件的核心挑战和最佳实践。以下是结构化的总结和建议。
核心挑战识别


上下文过载：AI 无法处理整个 monorepo 的代码（如 800 万行），导致建议不相关、速度慢或产生“幻觉”。
配置碎片化：不同工具（Claude Code, Cursor, Copilot）使用不同的配置文件（CLAUDE.md, .cursor/rules/, copilot-instructions.md, AGENTS.md），导致重复和维护困难。
发现与一致性：随着规则文件增多，人和 AI 都难以找到正确的指引，且难以保证跨模块的代码一致性（如设计模式、工具函数复用）。
团队协作：如何让多名开发者共享并维护一套统一的 AI 规则，避免每个人都有自己的“魔法咒语”。

最佳实践提炼（结构化方案）

1. 配置哲学：模块化引用 vs. 代码生成


模块化引用 (主流推荐)：

核心理念：将庞大的 CLAUDE.md 拆分为小型、专注的文档，在主文件中引用。
具体做法：

在 monorepo 根目录创建 /docs/ 或 .ai-rules/ 目录。
创建细分的文档：PROJECT_ARCHITECTURE.md, CODING_STANDARDS.md, DATABASE_SCHEMA.md, AUTH_FLOW.md 等。
在根 CLAUDE.md 中使用 @/docs/ARCHITECTURE.md 语法引用。这会将引用文件的内容自动载入初始上下文。
为不同应用/包（apps/, libs/）创建各自的 CLAUDE.md，引用公共文档并补充特定规则。


优点：上下文精简，易于维护，信息结构清晰。
社区案例：多位用户采用此方式，并强调使用 emoji（如 🚨、🔐）标注文档重要性以引导 AI。


代码生成/脚手架 (应对复杂模式)：

核心理念：当 AI 难以遵循复杂设计模式时（如错误的文件位置、不遵循仓库模式），不依赖文档，而是为 AI 提供代码生成工具。
具体做法：

使用 MCP（Model Context Protocol）服务器（如 scaffold-mcp）或内部脚本。
工具接收参数（如组件名、类型），输出结构化的骨架代码（如包含正确导入和接口的模板文件）。
AI 的任务变为“填空”，在保证结构正确的前提下填充业务逻辑。
在文件顶部用注释声明模式规则（如 /** PATTERN: Repository Pattern - MUST use dependency injection... */）。


优点：强制执行代码规范，极大提升生成代码的首次通过率，适合有成熟模式沉淀的团队。
社区案例：vuongagiflow 在帖子《Lessons Learned... Part 1: Scaffolding》中详细阐述了此方法。


2. 工作流策略：高频度的有意压缩


核心理念：主动、频繁地管理 AI 的上下文窗口，避免其被无关信息淹没。
推荐流程：

研究：启动新会话，让 AI 分析特定问题涉及的文件和流程，输出 RESEARCH.md。
计划：基于研究，让 AI 制定详细的实施计划，列出步骤、涉及文件、测试点，输出 PLAN.md。
实施：分阶段执行计划。每个阶段完成后，压缩上下文（例如，将当前状态总结更新到 PLAN.md 中），然后开始下一阶段。


Monorepo 适配：

始终从 monorepo 根目录启动 Claude Code/Cursor，以便 AI 感知整体结构。
在任务描述中明确指出工作目录（如“在 ./apps/admin 目录下，参考 ./libs/auth 的实现，完成 X 功能”）。
利用 monorepo 优势，让 AI 在不同模块间建立联系。


3. 多工具统一管理


目标：为 Claude Code、Cursor、Copilot 等维护单一事实来源。
具体方案：

在 monorepo 根目录创建 .ai-rules/ 目录作为共享规则库。
在此目录下存放模块化的规则文件（如 architecture.md, conventions.md）。
配置各工具引用这些共享文件：

Claude Code: 在 CLAUDE.md 中使用 @.ai-rules/architecture.md。
Cursor: 在 .cursor/rules/global.mdc 中使用 @.ai-rules/architecture.md（注意相对路径）。
GitHub Copilot: 在 .github/copilot-instructions.md 中也可引用或说明规则位置。


优点：一处修改，全局生效。避免同步脚本的复杂性。

4. 团队协作与规范


将 AI 规则视为代码：所有配置文件（CLAUDE.md, .ai-rules/, .cursor/）必须纳入版本控制（如 Git）。
建立贡献规范：鼓励开发者在解决 AI 的共性问题后，更新相应的规则文档。
提供标准模板：为新项目或模块提供预设的 CLAUDE.md 模板和目录结构。
文档发现性：

在主 README.md 或 CONTRIBUTING.md 中说明 AI 规则体系。
在根 CLAUDE.md 中清晰列出所有关键文档的索引和用途。


分层配置结构建议（针对大型 Monorepo）

your-monorepo/
├── .ai-rules/                    # 【核心】共享规则库（团队维护）
│   ├── 00-ROLE_AND_SCOPE.md     # AI角色、项目整体目标、技术栈
│   ├── 01-ARCHITECTURE.md       # 整体架构图、模块职责、数据流
│   ├── 02-CODING_STANDARDS.md   # 代码风格、命名规范、提交规范
│   ├── 03-TESTING_STRATEGY.md   # 测试框架、编写规范
│   ├── 04-BUILD_DEPLOY.md       # 构建、部署命令和环境变量
│   └── 05-COMMON_PATTERNS.md    # 常用设计模式（如Repository、组件结构）
├── docs/                         # 项目详细文档（也可被引用）
│   ├── database/
│   ├── api/
│   └── decisions/
├── apps/                         # 应用目录
│   ├── frontend/
│   │   ├── CLAUDE.md            # 引用根.ai-rules，补充前端特定规则
│   │   └── ...
│   └── backend/
│       ├── CLAUDE.md            # 引用根.ai-rules，补充后端特定规则
│       └── ...
├── libs/                         # 共享库目录
│   ├── shared-ui/
│   │   └── CLAUDE.md            # 组件库开发规则
│   └── data-access/
│       └── CLAUDE.md            # 数据访问层规则
├── CLAUDE.md                     # 【根入口】主要包含@引用和monorepo导航说明
├── .cursor/                      # Cursor规则（可引用.ai-rules）
│   └── rules/
│       └── global.mdc
├── .github/                      # GitHub Copilot指令
│   └── copilot-instructions.md
└── package.json / nx.json / ...  # 现有项目文件

关键结论与建议


放弃“万能提示词”：不存在一个能解决所有问题的魔法文件。成功的关键在于结构化、模块化的配置和精细化、分阶段的工作流管理。
拥抱“文档即代码”：将 AI 规则文件视为重要工程资产，进行设计、评审和维护。
选择适合团队成熟度的路径：

初级阶段：从模块化引用开始，整理现有知识到 .ai-rules/。
高级阶段：在模式固定且重要的领域（如项目初始化、特定服务生成），引入 MCP 脚手架来保证输出质量。


解决“最后一步”问题：无论配置多好，人的审查和引导仍是最高杠杆点。重点审查“研究”和“计划”文档，而不是逐行审查所有生成的代码。

通过实施以上策略，您可以将 AI 从一个容易“迷失”在大仓库中的工具，转变为一个理解项目上下文、遵循团队规范的高效协作者。

  
## gemini25.md

      
    Raw
  

              gemini25.md
            
          
    好的，我已经仔细阅读并分析了你提供的所有关于在大型单体仓库（monorepo）中管理 AI 编码助手（如 Claude Code, Cursor, GitHub Copilot）规则文件的 Reddit 帖子和 GitHub 讨论。
以下是从这些信息中提取、整合并结构化输出的最佳实践、策略和挑战。
核心原则与关键洞见

在深入具体策略之前，社区的经验汇集了几个核心思想：

上下文是王道 (Context is King)：所有策略的根本目标都是为 AI 提供精确且最小化的上下文。过大的上下文（如整个代码库）会导致 AI 迷失、性能下降和产生不相关的“废话代码 (slop)”。
分层与模块化是关键 (Hierarchy & Modularity)：不要试图用一个巨大的规则文件管理所有事情。采用分层结构，将全局规则与特定于应用/模块的规则分离开来。
人类在环路中至关重要 (Human-in-the-Loop is Crucial)：AI 不是全自动的魔法。最高效的工作流是在关键节点（如研究、规划阶段）进行人工审查和指导，这比审查最终生成的成百上千行代码更具杠杆效应。
从规则到脚手架的演进 (Evolution from Rules to Scaffolding)：单纯的指令性规则有其局限性。更高级的方法是提供“脚手架”或模板（Skeletons），让 AI 在预设的结构和模式中“填空”，以保证代码的一致性。


最佳实践与详细策略

根据社区的讨论，以下是几种被广泛采纳和推荐的最佳实践：
1. 文件结构与分层策略 (File Structure & Hierarchy)

这是最基础也是最重要的一步，社区普遍认同以下分层方法：


根目录 CLAUDE.md / .cursor/rules/global.mdc：

作用：定义全局上下文、项目整体架构、通用编码规范、技术栈概览以及开发者协作流程。
内容：应保持简洁，作为一个“索引”或“路由器”，通过引用（@语法）指向更详细的文档或子规则文件。
示例：
# 全局上下文
这是一个包含多个应用的 Monorepo。每个应用都有其独立的规则。

## 架构概览
- /apps/app1 - Vue.js 前端
- /libs/shared-ui - 共享组件库
- /services/api - .NET 后端服务

## 规则文件索引
- App1 规则: @./apps/app1/CLAUDE.md
- API 服务规则: @./services/api/CLAUDE.md


各应用/模块内的 CLAUDE.md 或规则文件：

作用：定义该特定模块的详细规则、设计模式、依赖关系和特定命令。
位置：放置在对应应用或库的根目录下（例如 apps/app1/CLAUDE.md）。
优势：当 AI 在特定目录下工作时，能自动加载最相关的上下文，避免全局上下文的干扰。


2. 上下文管理与优化 (Context Management & Optimization)

为了解决大型仓库的上下文窗口限制问题，开发者们创造了多种技巧：


使用文档引用 (@语法)：

做法：不要将所有架构文档、数据库模式、安全清单等长篇内容直接写入 CLAUDE.md。而是将它们存放在独立的 docs/ 目录中，然后在主规则文件中使用 @/docs/DATABASE_ARCHITECTURE.md 的方式引用。
优势：保持主规则文件简洁可管理，AI 只在需要时读取特定文档，极大节省了 Token 消耗。


“有意压缩”工作流 (Frequent Intentional Compaction)：

理念：将开发过程分解为 研究 (Research) -> 规划 (Plan) -> 实现 (Implement) 三个阶段，每个阶段都产生一个精炼的、压缩过的上下文（通常是 Markdown 文件）。
研究：让 AI（或子代理）探索代码库，生成一份关于当前任务相关文件、代码流和潜在问题的摘要。
规划：基于研究结果，让 AI 制定一个详细的、分步骤的行动计划 (PLAN.md)，包括要修改的文件和验证方法。这是人类审查的最佳时机。
实现：在一个全新的、干净的上下文中，让 AI 严格按照已批准的计划执行编码任务。


脚手架/骨架文件 (Scaffolding/Skeletons)：

问题：AI 常常忽略设计模式或重复造轮子。
解决方案：创建一个“脚手架”工具或简单的骨架文件。这些文件只包含最基本的结构、导入和带有规则注释的头部。
示例头部注释：
/**
 * PATTERN: Repository Pattern
 * - MUST use dependency injection
 * - MUST implement IRepository<T> interface
 * - NO direct database calls (use DataSource)
 * - ALL methods MUST be async
 */

效果：AI 会在此基础上进行“填空”，而不是从零开始，从而强制遵循既定模式。


3. 跨工具规则同步 (Cross-Tool Rule Synchronization)

为了避免为 Cursor、Claude Code 等不同工具维护多套重复的规则，社区提出了“单一事实来源”的方案：


创建统一的规则目录：

在项目根目录创建一个 .ai-rules/ 文件夹。
将所有通用的规则（如角色定义、命名规范、项目架构等）拆分成独立的 Markdown 文件存放在此。


在各工具的配置文件中引用：

CLAUDE.md:
@.ai-rules/role-definition.md
@.ai-rules/project-architecture.md
...

Cursor (.cursor/rules/project.mdc):
---
title: "Project Rules"
---
@../../.ai-rules/role-definition.md
@../../.ai-rules/project-architecture.md
...

优势：维护一处，所有工具同步更新。使用 @ 引用比符号链接（symlinks）具有更好的跨平台兼容性。


遇到的挑战与注意事项


AI 仍然会“犯错”：即使有完美的规则，AI 也可能忽略指令、产生幻觉或改变未经请求的代码（如路由、认证逻辑）。持续的监督和测试是不可或缺的。
规则维护成本：创建和维护这些规则文件本身就是一项新的工作。需要团队投入时间和精力，并将其视为与编写文档同等重要的任务。
启动成本高：对于一个拥有数百万行代码的庞大遗留系统，让 AI 有效工作可能需要一个专门的团队进行数月的投入和巨大的云预算。
工具的局限性：不同的 AI 工具（Cursor, Copilot, Claude Code）对规则的解析和遵循程度不同。需要针对性地进行测试和调整。

总结

在大型 Monorepo 中成功利用 AI 编码助手，不是一个简单的“即插即用”过程，而是一门需要技巧和策略的“上下文工程”手艺。
最终的理想方案是一个分层的、模块化的规则系统，它以一个简洁的全局文件为入口，通过引用链接到各个模块的特定规则和详细的架构文档。工作流上，推荐采用“研究-规划-实现”的模式，并在规划阶段进行严格的人工审核，以最小的投入获得最大的杠杆效应。同时，通过建立统一的 .ai-rules 目录，可以实现跨工具的规则同步，提高团队协作效率。

  
## gemini3.md

      
    Raw
  

              gemini3.md
            
          
    这是一个非常普遍且痛点的工程问题。在大型 Monorepo（单体仓库）中，如果不加管理，AI 上下文会迅速“中毒”（Context Poisoning）——即 AI 被不相关的代码、过期的文档或错误的架构模式淹没，导致输出质量下降。
基于你提供的 Reddit 和 GitHub 讨论，我为你总结了一套在大型 Monorepo 中管理 AI 规则的最佳实践。这套方案的核心理念是**“一次编写，多处引用”以及“分层上下文管理”**。
以下是结构化的实施指南：

1. 核心架构：单一事实来源 (Single Source of Truth)

不要为 Cursor 写一套规则，再为 Claude 写一套规则。这是维护的噩梦。
最佳实践：建立以 Markdown 为基础的原子化规则库。
在 Monorepo 的根目录创建一个专门的文件夹（例如 .ai-docs/ 或 docs/ai-standards/），存放与工具无关的纯文本规则。
推荐目录结构：
monorepo-root/
├── .ai-docs/                  # 核心规则库
│   ├── roles.md               # 定义 AI 的角色（你是资深架构师...）
│   ├── tech-stack.md          # 全局技术栈版本（Node v20, React v18...）
│   ├── coding-standards.md    # 命名规范、代码风格
│   ├── testing-policy.md      # 测试要求
│   └── architecture/          # 架构文档
│       ├── database.md
│       └── auth-flow.md
├── apps/
│   ├── web-client/            # 前端项目
│   │   ├── .cursor/rules/     # Cursor 规则（引用根目录）
│   │   └── CLAUDE.md          # Claude 规则（引用根目录）
│   └── api-server/            # 后端项目
└── packages/                  # 共享库

为什么这样做？

模块化： 修改命名规范只需改一个文件，所有工具自动生效。
兼容性： Claude Code (CLAUDE.md) 和 Cursor (.mdc) 都支持引用外部 Markdown 文件。


2. 策略：分层上下文 (Layered Context)

不要试图把整个 800 万行代码的上下文塞给 AI。你需要像剥洋葱一样管理规则。
第一层：全局通用规则 (Root Level)

适用于所有项目的内容。例如：Git 提交规范、公司层面的安全要求、代码审查标准。
第二层：项目特定规则 (Project/App Level)

在 apps/web-client/ 下的规则应该只包含前端相关的内容。

Cursor 配置： 使用 .cursor/rules/*.mdc。
Claude 配置： 在子目录下放置 CLAUDE.md。

第三层：按需引用的地图 (The "Map" Strategy)

对于大型项目，不要把所有架构文档都喂给 AI。创建一个**“索引文件”**（Map），告诉 AI 去哪里找信息，而不是直接给它信息。
示例索引文件 (docs/MAP.md)：
# 项目文档索引
- **数据库架构**: 详见 `.ai-docs/architecture/database.md` 🔴 (修改 Schema 前必读)
- **认证流程**: 详见 `.ai-docs/architecture/auth-flow.md`
- **新功能规范**: 详见 `docs/specs/new-feature-v2.md`

技巧： 使用表情符号（🔴, 🚨）标记关键文档，AI 对此非常敏感。
效果： AI 会先读取索引，发现需要修改数据库时，再去主动读取 database.md，节省 Token 并提高准确度。


3. 工具具体实现指南

A. Cursor (.cursor/rules)

Cursor 现在的最佳实践是放弃根目录巨大的 .cursorrules 文件，转而使用 .cursor/rules/ 目录下的多个 .mdc 文件，并利用 glob 模式进行自动化上下文注入。
示例：apps/web-client/.cursor/rules/react-best-practices.mdc
---
description: 前端 React 开发规范
globs: apps/web-client/**/*.tsx, apps/web-client/**/*.ts  # 仅在编辑这些文件时自动触发
alwaysApply: false
---

# 引用通用规则
@../../.ai-docs/coding-standards.md

# 项目特定规则
1. 使用 TanStack Query 进行数据获取。
2. 组件必须使用 TypeScript 接口定义 Props。
B. Claude Code (CLAUDE.md & AGENTS.md)

Claude Code 支持使用 @ 符号导入其他文件。
示例：apps/web-client/CLAUDE.md
# Claude 行为准则

## 导入核心规则 (使用相对路径)
@../../.ai-docs/roles.md
@../../.ai-docs/tech-stack.md

## 本地规则
- 这是一个 Next.js 项目。
- 运行测试命令: `pnpm test`
- 启动命令: `pnpm dev`

注意： 对于更高级的 Agent 行为（如自动规划），可以在根目录使用 AGENTS.md，并让 Claude 在需要时读取它。


4. 团队协作与同步 (Team & Sync)

当团队规模变大，单纯靠文件引用可能会出现路径错误或不一致。
方案 A：Git 子模块或 Monorepo 共享包 (推荐)
如果你的规则非常通用，可以将其做成一个独立的 Git Repo，作为 Submodule 引入，或者在 Monorepo 中作为一个 internal-docs 包。
方案 B：相对路径引用 (最简单)
在 Monorepo 中，使用 ../../ 这样的相对路径引用是最稳健的方法。它不需要额外的脚本，且 Cursor 和 Claude 都能解析。
方案 C：预提交钩子 (Pre-commit Hook)
编写一个简单的脚本，检查 .cursor/rules 或 CLAUDE.md 中的引用链接是否有效（即文件是否存在）。防止开发者移动了文档却忘了更新规则。
5. 高级技巧：上下文压缩 (Context Compaction)

在讨论中提到的一个重要技巧是应对长会话后的“上下文遗忘”。

"Brief" 模式： 不要依赖工具自带的上下文压缩。定义一个 /brief 命令或规则，要求 AI 在长时间对话后，将当前的决策、改动摘要写入一个 session-brief.md 文件。
Scaffold MCP： 对于新功能的开发，不要让 AI 凭空写。使用 MCP (Model Context Protocol) 工具或简单的脚本，先生成符合架构规范的空文件（Scaffold），再让 AI 填空。这比让 AI 从零生成文件结构的准确率高得多。

总结行动清单


重构目录：建立 .ai-docs 文件夹，提取通用规则。
拆分 Cursor 规则：利用 Globs 功能，将规则限制在特定目录生效（例如后端规则不出现在前端文件编辑中）。
配置 Claude 引用：使用 @ 语法在子项目 CLAUDE.md 中引入核心文档。
建立索引 (Map)：创建一个包含关键文档路径的列表，放在 AI 的系统提示词或高优先级规则中，引导它按需读取。

这套体系能够让你的 AI 助手从“因为上下文混乱而帮倒忙的实习生”，转变为“熟悉整个 Monorepo 架构的资深工程师”。

  
## kimi-k2-thinking.md

      
    Raw
  

              kimi-k2-thinking.md
            
          
    大 monorepo 中 AI 规则文件管理的最佳实践

基于多个社区讨论和实战经验，以下是系统化的最佳实践方案：

一、核心原则与哲学

1.1 分层上下文管理

核心思想：不要试图让 AI 理解整个代码库，而是建立分层、可导航的上下文体系。

人类开发者原则：你不会让新员工先读完 800 万行代码再开始工作
AI 同理：将任务拆分为"发现→计划→实现"三阶段，每阶段只加载必要上下文
上下文利用率：保持在 40-60% 的上下文窗口使用率，超过 80% 质量急剧下降

1.2 频繁有意压缩（Frequent Intentional Compaction）

关键策略：主动管理上下文，而非被动等待溢出。

每 3-5 轮对话后执行 /clear 或写入进度文件
使用 /compact 或自定义 Brief 模式保存关键状态
避免让 AI 自动搜索文件，而是明确告知路径


二、文件组织策略

2.1 分层放置规则文件

monorepo-root/
├── CLAUDE.md                    # 全局入口，仅引用和概述
├── .cursor/
│   ├── rules/
│   │   ├── base.mdc            # 全局规则（glob: "*"）
│   │   ├── frontend.mdc        # 前端专用（glob: "apps/frontend/**/*"）
│   │   └── backend.mdc         # 后端专用（glob: "apps/backend/**/*"）
│   └── instructions/           # 可选：更细粒度的指令
├── .ai-rules/                  # 多工具共享规则（见第4节）
├── docs/
│   ├── architecture/           # 架构文档
│   ├── features/               # 功能规格
│   └── decisions/              # 决策记录
└── apps/
    ├── frontend/
    │   └── CLAUDE.md           # 可选：子项目专用
    └── backend/
        └── CLAUDE.md           # 可选：子项目专用

规则：

根级 CLAUDE.md：不超过 300 行，只作索引和关键规则
子目录 CLAUDE.md：仅在需要强隔离时创建（如技术栈差异大）
避免过度分散：50+ 个 CLAUDE.md 难以维护

2.2 多工具统一目录

创建 .ai-rules/ 作为单一真相源：
.ai-rules/
├── 00-role-definition.md       # AI 角色定义
├── 01-critical-rules.md        # 安全/关键规则
├── 02-architecture.md          # 架构概述
├── 03-naming-conventions.md    # 命名规范
├── 04-coding-standards.md      # 代码风格
└── 05-workflows.md             # 工作流命令

三、内容结构与层次

3.1 CLAUDE.md 的黄金结构

# 项目概述
- **目的**：一句话说明项目目标
- **技术栈**：关键技术和版本
- **架构图**：ASCII 或链接到图表

# 关键文档引用（核心技巧）
## 📚 关键文档模式
**重要**：创建新文档时立即在此添加引用

- **架构**：@docs/architecture/SYSTEM.md
- **数据库**：@docs/database/SCHEMA.md 🚨
- **认证**：@docs/security/AUTH.md 🔐
- **部署**：@docs/ops/DEPLOYMENT.md

# 全局规则（极简）
- 必须遵循现有设计模式
- 禁止硬编码，使用配置系统
- 所有方法必须是异步的（如适用）

# 项目结构
apps/
  frontend/          # Vue 3 应用，见 @apps/frontend/CLAUDE.md
  backend/           # .NET API，见 @apps/backend/CLAUDE.md
libs/
  shared/            # 共享工具库
3.2 子文档模板

功能规格文档（docs/features/*.feat.md）：
# 功能名称规格

## 概述
- 目的：解决什么问题
- 影响范围：哪些模块受影响

## 技术栈
- 前端：React 18, TypeScript
- 后端：ASP.NET Core 8
- 数据库：PostgreSQL 15

## 关键组件
- **ComponentA**：负责 X
- **ServiceB**：处理 Y

## 实现步骤
1. 创建数据库迁移
2. 实现 API 端点
3. 添加前端组件
4. 编写集成测试

## 验证清单
- [ ] 单元测试覆盖率 >80%
- [ ] 手动测试关键路径
- [ ] 文档已更新

四、多工具同步方案

4.1 统一规则管理（推荐）

方案：使用 @ 引用语法共享规则
CLAUDE.md：
@.ai-rules/00-role-definition.md
@.ai-rules/01-critical-rules.md
@.ai-rules/02-architecture.md
.cursor/rules/base.mdc：
---
title: "基础规则"
glob: "*"
---

@../../.ai-rules/00-role-definition.md
@../../.ai-rules/01-critical-rules.md
优点：

✅ 单一维护点
✅ 无需同步脚本
✅ 版本控制清晰

注意事项：

路径问题：确保相对路径在所有工具中有效
团队培训：新人需要理解此结构

4.2 替代方案：符号链接

# 在 Linux/macOS
ln -s .ai-rules/role-definition.md CLAUDE.md
ln -s .ai-rules/cursor-rules.md .cursor/rules/base.mdc

# Windows (需管理员权限）
mklink CLAUDE.md .ai-rules\role-definition.md
缺点：Git 不友好，跨平台兼容性问题
4.3 不推荐：手动同步


容易出错
增加认知负担
长期不可持续


五、上下文管理技术

5.1 会话生命周期管理

理想会话流程：

启动：claude /start + 读取关键文档
发现：使用子代理探索代码库，输出到 research.md
计划：基于发现生成 plan.md，人类审核
实现：分阶段执行，每阶段后验证
压缩：上下文达 60% 时写入 brief.md 并重启
结束：清理临时文件，更新主文档

关键命令：
# 检查上下文使用率
/status

# 手动压缩
Write a comprehensive brief covering progress, decisions, and next steps to brief.md

# 重启会话
/clear
/start and please read brief.md and plan.md
5.2 子代理模式

用途：隔离探索性工作，避免污染主上下文
示例：
# 主会话
I need to add user authentication. Please research the current auth system.

# 子代理执行
Task: Research authentication implementation
- Search for existing auth files
- Analyze middleware patterns
- Identify database tables
- Output summary to auth-research.md

# 主会话读取结果后制定计划
Based on auth-research.md, create a plan to add OAuth2 support.
5.3 智能文档索引

使用 MCP 服务器：

Heimdall MCP：自动解析架构文档和 Git 历史为记忆
Serena MCP：基于 LSP 的代码导航
ChromaDB MCP：向量搜索文档

配置：
{
  "mcpServers": {
    "heimdall": {
      "command": "docker",
      "args": ["run", "-p", "8000:8000", "heimdall-mcp"]
    },
    "serena": {
      "command": "npx",
      "args": ["@sourcegraph/serena-mcp"]
    }
  }
}

六、团队协作最佳实践

6.1 文档所有权


架构文档：由架构师维护，代码审查时检查
功能规格：由产品经理/技术负责人编写
规则文件：由团队共同维护，变更需 PR 审查

6.2 审查流程

AI 生成代码审查重点：

计划审查：在实现前审查 plan.md（最高杠杆）
测试审查：确保测试覆盖真实场景，非虚假通过
架构一致性：检查是否遵循现有模式
安全审计：特别注意认证、授权、数据访问

规则：AI 代码必须通过人类审查才能合并
6.3 新人 onboarding


提供 onboarding.md 指引
创建示例 PR 展示完整流程
设置配对编程会话，实时指导 AI 使用
维护常见问题 FAQ


七、工作流模式

7.1 全栈功能开发

场景：需要同时修改前端、后端和数据库
步骤：

根目录启动：claude /start 从 monorepo 根
指定范围："在 apps/frontend 添加用户界面，参考 apps/backend/lambda/users 的 API 设计"
生成计划：输出到 features/user-management/plan.md
分阶段实施：

Phase 1: 后端 API 和数据库迁移
Phase 2: 前端组件和状态管理
Phase 3: 集成测试和文档


跨服务验证：使用 Playwright 截图验证端到端流程

7.2 遗留代码现代化

策略：

文档优先：让 AI 分析并生成 docs/legacy/system-X.md
模式提取：识别可复用的设计模式，创建模板
渐进重构：每次只重构一个模块，保持测试通过
脚手架辅助：使用 MCP 生成符合新模式的骨架代码

关键：不要试图让 AI 一次性理解整个遗留系统

八、常见陷阱与反模式

❌ 陷阱 1：过度依赖 AI 自动发现

问题：让 AI 自由搜索文件，导致上下文混乱和幻觉
解决：明确指定路径和参考文件
❌ 陷阱 2：单文件过大

问题：500+ 行的 CLAUDE.md 导致 AI 无法区分重要性
解决：拆分为引用文档，主文件 <300 行
❌ 陷阱 3：规则冲突

问题：多个 .cursorrules 和 CLAUDE.md 内容矛盾
解决：建立 .ai-rules/ 单一真相源
❌ 陷阱 4：忽视人类审查

问题：直接合并 AI 代码，导致技术债累积
解决：强制计划审查和测试验证
❌ 陷阱 5：上下文过载

问题：一次加载整个 monorepo，超出 token 限制
解决：使用 @package 或子目录作用域
❌ 陷阱 6：文档过时

问题：AI 读取旧文档，生成错误代码
解决：在 CLAUDE.md 顶部添加：
## 📌 文档更新规则
- 修改代码后必须更新相关文档
- 删除过时引用
- 添加新文档时立即在此列出

九、工具特定注意事项

9.1 Claude Code


自动读取：启动时自动读取 CLAUDE.md 和 @ 引用文件
会话记忆：使用 /compact 或自定义 Brief 模式
子代理：Task() 工具隔离探索工作
MCP 支持：优先使用 MCP 而非长上下文

9.2 Cursor


规则选择：使用 glob 模式精确控制作用域
全局规则：文件名前缀 * 应用于所有请求
性能：本地索引最多 2500 个文件，超量需排除
工作区：使用 .code-workspace 管理多仓库

9.3 GitHub Copilot


索引限制：750 文件自动索引，2500 文件硬上限
多根工作区：需要手动创建 .code-workspace
自定义指令：支持 AGENTS.md 和 .github/copilot-instructions.md
作用域：缺乏 @package 功能，需依赖文件排除


十、高级技巧

10.1 动态规则生成

# 使用脚本根据代码生成规则
./scripts/generate-rules.sh --analyze patterns --output .ai-rules/
10.2 测试驱动验证

# 让 AI 生成测试后立即运行
claude "实现功能 X，然后运行 npm test，如果失败则修复"
10.3 令牌优化


使用 emoji 替代长文本（🚨 表示关键，🔐 表示安全）
移除历史参考，只保留当前状态
使用 @ 引用而非内联内容

10.4 紧急回滚

在 CLAUDE.md 中添加：
## 🚨 紧急停止
如果 AI 试图：
- 修改认证/路由配置
- 推送敏感数据
- 覆盖 .gitignore

立即执行：`/cancel` 并报告团队

总结：最小可行方案

对于刚开始的团队，采用以下最小配置：


创建 .ai-rules/ 目录，包含 3 个文件：

00-overview.md：项目概述
01-critical.md：必须遵守的规则
02-workflow.md：常用命令


根目录 CLAUDE.md：
@.ai-rules/00-overview.md
@.ai-rules/01-critical.md

## 📚 文档索引
- 架构：@docs/architecture.md
- 数据库：@docs/database.md


Cursor 规则：

.cursor/rules/base.mdc：全局规则，引用 .ai-rules/
按需创建子目录规则


工作流程：

每次任务：发现 → 计划 → 实现
每 5 轮对话：压缩上下文
每次合并：人类审查计划 + 测试


这套方案平衡了可维护性和实用性，可根据团队规模逐步扩展。

  
## qwen3.md

      
    Raw
  

              qwen3.md
            
          
    大型 Monorepo 中 AI 规则文件管理最佳实践指南

在大型 monorepo 环境中有效管理 AI 规则文件（如 CLAUDE.md、.cursor/rules 等）是提高 AI 编码助手效率的关键。基于多个开发团队的实际经验，以下是经过验证的最佳实践：
一、规则文件结构与位置

1. 层级化规则文件组织


根目录 CLAUDE.md：提供全局上下文和架构概览
# 全局上下文
本 Claude 环境管理包含多个应用的 monorepo。每个应用在 rules/appX.md 中有其作用域规则。

## 架构概览
Repo: my-monorepo/
├── apps/
│   ├── app1/
│   └── app2/
├── libs/
│   ├── shared/
│   └── domain-specific/
└── rules/
    ├── app1.md
    └── app2.md

## 预期行为
Claude 应：
- 仅使用相关 rules/appX.md 上下文中的规则
- 避免跨不相关应用污染逻辑
- 对全局系统行为参考此文件


子目录特定规则：在关键模块目录中放置特定规则文件

apps/、libs/、packages/ 等关键目录应有自己的 CLAUDE.md
每个子目录 CLAUDE.md 可引用根目录规则


2. 模块化规则系统


单一事实源方法（推荐）：
.ai-rules/                     # 单一事实源
├── role-definition.md         # AI 角色和能力
├── critical-rules.md          # 安全规则
├── naming-conventions.md      # 命名标准
├── project-architecture.md    # 技术栈和结构
├── coding-standards.md        # 代码风格指南
└── ...


Claude Code：在 CLAUDE.md 中引用
@.ai-rules/role-definition.md
@.ai-rules/critical-rules.md
@.ai-rules/naming-conventions.md


Cursor：在 .cursor/rules/project-rules.mdc 中引用
@../../.ai-rules/role-definition.md
@../../.ai-rules/critical-rules.md


3. 文档引用策略


使用 @ 语法引用详细文档，保持主文件简洁
关键文档应包含明确的返回索引链接
在根 CLAUDE.md 中维护"关键文档参考"部分：
### 🗺️ 关键文档参考
- **Docker 架构**: `/docs/DOCKER_ARCHITECTURE.md` 🐳
- **数据库架构**: `/docs/DATABASE_ARCHITECTURE.md`
- **认证流程**: `/docs/AUTH_FLOW.md` 🔐
- **安全检查表**: `/docs/SECURITY_CHECKLIST.md` 🚨


二、上下文管理策略

1. 避免上下文过载


不要将整个 monorepo 加载到上下文中
只提供当前任务相关的上下文
保持上下文窗口利用率在 40-60% 之间

2. 频繁有意压缩 (Frequent Intentional Compaction)

采用研究→计划→实施的工作流程：


研究阶段：

让 AI 理解代码库、相关文件和信息流
输出到 RESEARCH.md


计划阶段：

详细规划修复步骤和需要编辑的文件
输出到 PLAN.md
包含明确的验证点


实施阶段：

逐步执行计划，每阶段验证
完成后更新/删除 PLAN.md


3. 子代理使用


使用子代理处理特定任务（如文件搜索、代码理解）
保持主代理上下文简洁
子代理输出应结构化，便于主代理使用

三、跨应用/全栈开发

1. 明确跨模块参考


清晰指示 AI 查看其他模块：

"在 admin 文件夹添加 Users 菜单项，查看 /lambda/users 了解用户 API 工作方式"


2. 分阶段开发


先处理前端，再处理后端（或反之）
使用计划文件确保一致性
为每个阶段创建单独的上下文

3. 架构文档


维护清晰的架构文档，描述模块间关系
包含依赖图、数据流和关键接口
让 AI 理解"为什么"而不仅仅是"怎么做"

四、提高规则文件可发现性

1. 架构概览


在根 CLAUDE.md 中包含简短架构描述
使用清晰的标签：[Tool: X], [Agent: Y]
明确说明输入/输出期望

2. 智能索引


使用 MCP 服务器（如 Serena）提供智能代码导航
考虑使用向量数据库（如 ChromaDB）创建语义索引
为大型代码库实现智能文件选择

3. 文档规范


为关键设计模式创建标准文档模板
在代码文件头部添加模式注释：
/**
 * PATTERN: Repository Pattern
 * - MUST use dependency injection
 * - MUST implement IRepository<T> interface
 * - NO direct database calls (use DataSource)
 * - ALL methods MUST be async
 */


五、实用技巧与陷阱避免

1. 避免常见陷阱


不要过度复杂化规则文件
不要假设 AI 会自动理解未明确说明的规则
不要在计划阶段跳过验证点

2. 高效工作流


3-5 条消息后 /clear，测试代码，然后开始新聊天
使用计划文件作为检查点
为关键任务保留 PLAN.md，完成后删除

3. 团队协作


将规则文件纳入版本控制
为规则变更建立审查流程
定期更新文档，反映代码库变化

六、工具集成建议

1. MCP 服务器


Serena MCP：用于代码导航和理解
Scaffold MCP：用于生成符合模式的代码
Heimdall MCP：用于上下文记忆管理

2. 规则同步


避免为不同工具维护重复规则
使用相对路径引用确保跨平台兼容性
考虑使用符号链接（如平台支持）

3. 工作区设置


对于非常大的 monorepo，考虑使用多工作区
每个工作区专注于特定应用或功能区域
使用 VS Code 工作区文件 (.code-workspace) 管理多仓库

结论

在大型 monorepo 中成功使用 AI 编码助手的关键在于有意的上下文管理和结构化的规则组织。不要试图让 AI 理解整个代码库，而是设计工作流程，使其在需要时获取必要的上下文。
最重要的是：人类应该专注于最高杠杆点——审查研究和计划，而不是审查代码。一个糟糕的研究可能导致数千行错误代码，而一个糟糕的计划可能导致数百行错误代码，但一个糟糕的代码审查只能修复少量错误。
通过实施这些最佳实践，团队可以显著提高 AI 编码助手在大型 monorepo 环境中的有效性和可靠性，同时保持代码质量和团队协作。
No results found