1. 项目概述：为复杂多仓库项目构建AI就绪的上下文

如果你和我一样，经常在多个相互关联的代码仓库之间切换，并且尝试让AI助手（比如Cursor或Claude Code）帮你理解整个系统的脉络，那你一定遇到过这样的困境：你打开一个前端项目，想让AI帮你修改一个组件，但它完全不知道这个组件依赖的后端API在另一个仓库里是如何定义的；或者你想重构一个共享的工具库，但AI助手根本不了解这个库在另外三个项目中的不同用法。结果就是，你得到的建议要么是片面的，要么是脱离实际架构的，甚至可能引入破坏性的变更。这就是典型的“上下文缺失”问题——AI只看到了你当前打开的文件，却对项目间的依赖关系和整体架构一无所知。

SPDUK/context-builder 这个项目，就是为了彻底解决这个问题而生的。它本质上是一个“元提示词”，或者说是一个高度结构化的指令集。你把它喂给你的AI助手，它会引导AI自动扫描你工作区里的所有项目，分析它们的结构、技术栈和相互依赖关系，然后生成一套完整的、机器可读的文档。这套文档包括每个项目的独立架构说明、依赖关系图，以及为不同AI工具（如Cursor的 .mdc 规则文件、Claude的 CLAUDE.md 助手文件）定制的“行为指南”。最终，你的AI助手就像获得了一张精确的“系统地图”，它能基于对整个生态的理解来提供精准的代码建议，而不是在黑暗中盲目摸索。

这个工具特别适合那些拥有复杂多仓库工作区的开发者，比如微服务架构下的多个后端服务、一个设计系统库被多个前端应用引用、或者是一个核心SDK被多个客户端项目依赖的场景。它把原本需要你手动梳理、并且很难向AI传达的隐性知识，变成了结构化的显性文档。接下来，我会详细拆解它的设计思路、具体怎么用、以及我在实际部署中积累的一些关键技巧和避坑指南。

2. 核心设计思路与工作原理拆解

2.1 从“单项目上下文”到“系统级上下文”的范式转换

传统的AI编码助手，其工作模式是“基于当前打开文件的上下文进行推理”。Cursor或Claude Code会读取你当前编辑的文件、以及可能相关的邻近文件，来理解局部逻辑。但对于跨仓库的调用、共享的类型定义、或者分布在多个项目中的配置，它们是无能为力的。Context Builder的核心思路，是进行了一次范式转换： 从为单个任务提供上下文，转变为为整个工作区生态系统构建上下文 。

它不再满足于回答“这个函数怎么改”，而是先要回答“这个函数在整个系统中扮演什么角色，它依赖谁，又被谁依赖”。为了实现这一点，它的设计遵循了几个关键原则：

1. 自动化发现而非手动配置 ：它不需要你预先编写一个 workspace.json 来声明项目关系。相反，它通过分析目录结构、包管理文件（如 package.json 、 go.mod 、 Cargo.toml ）、导入语句（如 import 、 require ）来自动推断项目边界和依赖关系。这大大降低了使用门槛，尤其适合那些历史包袱重、文档不全的项目群。
2. 生成双模文档 ：它生成的文档既是给人看的（清晰的Markdown），也是给AI看的（结构化的数据）。例如， ARCHITECTURE.md 会用自然语言描述项目职责，同时其中包含的代码块、列表和特定关键词（如“Tech Stack: React, TypeScript, Vite”）也极易被AI解析和理解。
3. 工具链适配 ：它没有绑定在单一AI工具上。通过生成 .mdc （Cursor规则）、 CLAUDE.md （Claude专用提示）等不同格式的文件，它确保了无论你使用哪种主流AI编码助手，都能获得量身定制的上下文支持。这种设计体现了其实用主义导向。

2.2 元提示词：将复杂流程编码为可执行的指令

Context Builder本身不是一个需要安装的软件或CLI工具，它就是一个名为 prompt.md 的文本文件。它的强大之处在于，它是一份极其详尽的“任务说明书”，指导AI如何一步步完成从分析到文档生成的全过程。我们可以把它理解为一个“超级工作流”。

当你把这份冗长的提示词粘贴给AI时，实际上是在下达一个复合指令序列。一个设计精良的元提示词，通常会包含以下几个部分，Context Builder也基本遵循了这个结构：

• 角色与目标设定 ：首先明确告诉AI“你现在是一个高级系统架构分析专家”，你的目标是分析多仓库工作区并生成文档。这步很重要，它设定了AI的“人格”和专业领域。
• 输入与范围界定 ：指示AI去读取当前工作区的根目录，列出所有子项目，并以此作为分析范围。这防止了AI去分析无关的系统目录。
• 分步操作流程 ：这是核心。提示词会详细列出每一步该做什么：
  1. 项目识别 ：遍历目录，根据某些特征（如存在 package.json 、 pyproject.toml 等）识别独立项目。
  2. 单个项目分析 ：对每个项目，分析其 package.json （或类似文件）获取元数据（名称、版本、依赖），扫描关键目录（ src/ , components/ , api/ ），阅读配置文件（如 vite.config.ts , docker-compose.yml ）来理解构建和运行方式。
  3. 依赖关系分析 ：跨项目分析导入语句，找出项目A引用了项目B的本地路径（如 “@my-org/shared-ui”: “file:../shared-ui” ），或者通过代码分析发现跨项目的API调用。
  4. 文档生成 ：按照预定义的模板，将上两步收集的信息填充到 ARCHITECTURE.md 和 DEPENDENCIES.md 中。
  5. 规则文件生成 ：基于项目的技术栈（如发现使用了Zod、Prisma），生成对应的AI行为规则，例如“在本项目中，数据验证请使用Zod”。
• 输出格式规范 ：严格规定生成文件的位置（如每个项目下的 ai/ 目录）、文件名、Markdown的标题层级、代码块的语法高亮等。这保证了输出的一致性。
• 容错与回退机制 ：好的元提示词会预见到可能的问题。例如，它会指示AI：“如果某个项目没有 package.json ，则尝试通过目录结构和文件类型来推断其技术栈”。

这种将复杂、多步骤的分析任务编码进一个提示词的做法，是提示词工程的高级应用。它本质上是在对AI进行“一次性的复杂编程”。

2.3 依赖关系映射的智能推断策略

依赖分析是Context Builder最核心也最复杂的部分。它不能仅仅看 package.json 里的 dependencies ，因为那里列出的通常是发布到npm或PyPI的公共包。对于本地项目间的依赖，需要更精细的策略。根据我的实践和对其提示词思路的解读，它通常采用多管齐下的方式：

1. 包管理器链接分析 ：这是最直接的一环。它会检查每个项目的包管理文件，寻找指向本地文件路径的依赖项。在JavaScript/TypeScript生态中，这表现为 package.json 中类似 “@internal/shared-lib”: “file:../shared-lib” 的条目。在Python中，可能是 pyproject.toml 里 path = ../common-utils 的依赖。这是推断项目间强依赖关系的黄金标准。
2. 源代码导入分析 ：即使包管理器文件没有显式声明，项目间也可能通过相对路径或配置的别名直接导入代码。AI会扫描源代码中的 import / require 语句，寻找指向兄弟目录的路径，例如 import utils from ‘../../common/src/utils’ 。这能发现那些“非正式”或配置化的依赖。
3. 配置与部署文件分析 ： docker-compose.yml 、 Kubernetes 配置文件、CI/CD流水线文件（如 .github/workflows/*.yml ）常常揭示了服务间的运行时依赖。例如，一个服务的 depends_on 字段指向另一个服务，这明确指示了它们之间的启动顺序和网络依赖关系。
4. 通用依赖推导 ：如果两个项目都重度依赖同一个特定的第三方库（比如都使用了 axios@^1.5.0 进行HTTP请求，且配置了相同的拦截器逻辑），AI可能会在文档中备注这种“共同技术选择”，虽然这不是严格的代码依赖，但对于理解系统统一风格很重要。

通过这些层次的交叉验证，Context Builder能够绘制出一幅相对准确的“项目关系图谱”，并以Mermaid图的形式可视化出来，这对于人类理解和后续的架构评审都极具价值。

3. 完整部署与实操指南

3.1 前期准备与工作区结构化

在你运行那个庞大的元提示词之前，花点时间整理你的工作区是事半功倍的做法。Context Builder虽然能处理一定程度的混乱，但一个清晰的结构能让它分析得更准确，生成的文档也更易读。

理想的工作区结构：

my-enterprise-workspace/      # 工作区根目录
├── services/                  # 后端微服务目录
│   ├── user-service/         # 用户服务 (Node.js + Express)
│   ├── product-service/      # 产品服务 (Python + FastAPI)
│   └── payment-service/      # 支付服务 (Go)
├── apps/                     # 前端应用目录
│   ├── admin-dashboard/      # 管理后台 (React + TypeScript + Vite)
│   └── customer-portal/      # 客户门户 (Next.js)
├── libraries/                # 共享库目录
│   ├── shared-types/         # 共享TypeScript类型定义
│   ├── design-system/        # UI组件库 (React + Tailwind)
│   └── api-client-sdk/       # 统一API客户端SDK
└── infrastructure/           # 基础设施代码
    ├── terraform/            # IaC配置
    └── docker-compose.yml    # 本地开发环境编排

关键准备步骤：

1. 统一包管理器与锁文件 ：确保每个项目都使用了正确且更新的包管理文件。对于Node.js项目，检查 package.json 中的 name 和 version 字段是否准确，本地依赖的 file: 路径是否正确。删除无用的 node_modules 文件夹，让AI专注于分析源码和声明文件，而不是庞大的二进制依赖。
2. 清理临时与生成文件 ：将 dist/ , build/ , .next/ , __pycache__/ 等目录添加到项目的 .gitignore 中。在运行Context Builder前，也可以临时删除或忽略它们。这些目录会极大增加AI的解析负担，并可能引入干扰信息。
3. 检查内部依赖声明 ：手动检查各个项目中对内部共享库的引用。确保在 package.json 或 pyproject.toml 中，内部依赖使用的是相对路径（ file:../libraries/shared-types ），而不是一个可能不存在的npm包名。这是生成准确依赖图的基础。
4. 准备一个“干净”的AI会话 ：建议在一个全新的AI聊天会话中粘贴元提示词。如果之前的对话历史很长且混杂了其他话题，可能会干扰AI对这份复杂指令的理解和执行。在Cursor或Claude中，直接开启一个新标签页进行操作是最稳妥的。

3.2 分步执行元提示词

假设你已经将相关项目都添加到了Cursor或Claude Desktop的同一个工作区中，并且工作区结构大致清晰。

1. 获取元提示词 ：前往SPDUK/context-builder的GitHub仓库，找到核心的 prompt.md 文件。全选并复制其全部内容。这个文件可能很长（数千字），确保完整复制。
2. 在AI聊天框中粘贴 ：打开你的AI助手（Cursor的AI面板或Claude的对话界面），将复制的内容完整粘贴进去，然后发送。 这里有一个重要技巧：不要做任何修改，先原样发送。 这个提示词是经过精心设计的，开头可能包含对AI的初始指令，任何前置的你的话语都可能破坏其结构。
3. 等待并观察AI的“思考”过程 ：发送后，AI会开始“工作”。你会看到它输出大量的分析过程，比如“正在扫描根目录...”、“发现项目：user-service”、“分析package.json...”、“检测到对shared-types的依赖”等等。这个过程可能会持续几分钟，并且消耗大量的上下文Token（所以确保你的AI模型有足够的上下文长度，如Claude 3.5 Sonnet 200K或GPT-4 Turbo 128K）。 在此期间，不要打断它，也不要问其他问题。
4. 处理中断与续接 ：有时由于上下文长度限制或网络问题，AI的响应可能会在中途截断。如果发生这种情况， 不要慌张，也不要重新发送整个提示词 。最常见的做法是，简单地输入“请继续”或“继续生成”。一个设计良好的元提示词内部通常包含了状态管理逻辑，AI会尝试从上次中断的地方继续。如果“继续”无效，你可以引用它最后生成的一段内容，然后说“请从创建 product-service/ai/DEPENDENCIES.md 文件之后继续”。
5. 审查生成的文件 ：当AI最终输出“所有文档已生成完毕”或类似信息后，去你的文件系统中检查。你应该在每个项目的根目录下看到新生成的 ai/ 文件夹，里面包含 ARCHITECTURE.md 和 DEPENDENCIES.md 。在项目根目录可能看到 CLAUDE.md ，在 .cursor/rules/ 目录下看到 .mdc 文件。工作区根目录下会有 ai/WORKSPACE_OVERVIEW.md 。

注意 ：首次运行时，AI可能会因为权限问题无法直接在你磁盘上创建文件。它通常会将文件内容以代码块的形式输出给你。这时你需要手动创建这些文件和目录，并将内容复制进去。后续运行如果AI有文件读写权限（如Cursor的Composer模式），则可能直接写入。

3.3 生成文件详解与定制化

让我们深入看看生成的这些文件，理解它们的用途，并知道如何根据自己团队的需求进行微调。

ai/ARCHITECTURE.md 这是单个项目的“身份证”和“设计文档”。一个高质量的生成文件应包含：

• 项目概述 ：用一两句话说明这个项目是干什么的（例如：“ user-service 负责处理所有用户相关的业务逻辑，包括注册、登录、鉴权和用户资料管理”）。
• 技术栈 ：清晰列出核心框架、语言版本、关键库（如“Node.js 18, Express 4.18, PostgreSQL, Prisma ORM, Jest for testing”）。
• 目录结构说明 ：不是简单罗列文件夹，而是解释关键目录的职责。例如：“ src/routes/ 包含所有Express路由处理器； src/services/ 包含核心业务逻辑； prisma/ 存放数据库schema和迁移文件”。
• 核心数据流 ：描述一个典型请求（如“用户登录”）在本项目内经过哪些模块处理。
• 公共API/接口 ：如果是库或API服务，列出主要的导出函数、类或API端点。
• 如何启动 ：给出本地开发环境下的启动命令（如 npm run dev , docker-compose up ）。

ai/DEPENDENCIES.md 这是项目的“社会关系图”。它应该包含：

• 内部依赖 ：明确列出本项目所依赖的其他本地项目，并说明依赖性质（是代码引用、类型依赖还是构建时依赖）。
• 外部依赖 ：列出关键的三方库，并最好附带一句为什么选择它（例如：“使用 axios 进行HTTP请求，因其拦截器功能对统一错误处理至关重要”）。
• 被谁依赖 ：列出哪些其他本地项目依赖于此项目。这部分对于评估变更的影响范围极其重要。
• 依赖图 ：一个Mermaid格式的图形，直观展示上述关系。

.cursor/rules/project-name.mdc 与 CLAUDE.md 这些是“AI行为守则”。它们将技术栈选择固化成了规则。例如，在一个使用Tailwind和Radix UI的项目中，生成的 .mdc 规则可能包含：

- **样式规则**：所有组件样式必须使用Tailwind CSS工具类实现。禁止编写单独的`.css`或`.scss`文件。对于复杂交互状态，使用`@apply`指令或Tailwind插件。
- **组件库规则**：基础UI组件（如按钮、对话框、下拉菜单）必须优先从`@radix-ui/react`系列包中选用。只有在Radix UI不提供的情况下，才考虑自行构建。
- **数据获取规则**：前端数据获取必须使用`react-query`库，并遵循其`useQuery`/`useMutation`范式。禁止直接使用`fetch`或`axios`在组件内发起请求。
- **状态管理规则**：局部状态使用React `useState`/`useReducer`，跨组件状态使用Zustand。禁止在本项目中使用Redux。

CLAUDE.md 内容类似，但格式更贴近Claude的提示词风格。 你可以手动编辑这些规则文件 ，加入你们团队特有的编码规范，比如“函数命名必须采用驼峰式”、“API响应必须用Zod Schema验证后再使用”。

ai/WORKSPACE_OVERVIEW.md 这是整个系统的“总览图”。它应该：

• 列出工作区内所有项目及其一句话描述。
• 绘制一个全局的、跨项目的依赖关系图。
• 说明关键的跨项目集成点（例如：“ admin-dashboard 通过 api-client-sdk 调用 user-service 和 product-service 的API”）。
• 描述通用的开发实践和工具链（如“所有项目使用统一的ESLint和Prettier配置，位于 libraries/eslint-config ”）。

4. 高级技巧与深度集成方案

4.1 将Context Builder融入团队工作流

一次性生成文档很棒，但如何让它持续产生价值，而不是迅速过时？这就需要将其集成到团队的日常开发流程中。

方案一：作为预提交钩子（Pre-commit Hook） 你可以在团队共享的Git钩子配置（如使用 husky 和 lint-staged ）中加入一个脚本。这个脚本不是直接运行AI（成本高且慢），而是做一次“轻量级校验”：检查 ai/ 目录下的文档最后一次生成时间，如果发现有任何项目的 package.json 或关键依赖文件比文档的修改时间更晚，就提示开发者“架构文档可能已过期，建议重新运行Context Builder更新”。这只是一个提醒，不会阻塞提交。

方案二：集成到CI/CD流水线 在GitHub Actions或GitLab CI中创建一个定期（如每周日凌晨）或事件触发（如监测到 package.json 变更）的Job。这个Job可以：

1. 在一个配备了足够上下文长度AI模型API密钥的Runner上运行。
2. 自动检出代码，设置工作区。
3. 将最新的 prompt.md 发送给AI API（如OpenAI GPT-4 Turbo或Anthropic Claude的API）。
4. 接收生成的文档，并提交一个包含更新后文档的Pull Request。 这样，文档的更新就实现了自动化。但需要注意API调用成本和频率。

方案三：作为新成员入职工具 新同事加入项目时，让他/她首先在自己的开发环境上运行一次Context Builder。生成的 WORKSPACE_OVERVIEW.md 和各个项目的 ARCHITECTURE.md 是最好的系统入门教材，比零散的README更全面、更互联。可以要求新成员在熟悉系统后，对照生成的文档去阅读核心代码，并标记不理解的地方，这能极大提升入职效率。

4.2 针对不同技术栈的优化策略

原始的元提示词可能更偏向于JavaScript/TypeScript生态。如果你的工作区混合了其他语言，需要对其进行调整和增强。

对于Python项目：

• 在提示词中，需要指示AI重点分析 pyproject.toml 或 setup.py / requirements.txt 。
• 依赖分析要关注 [tool.poetry.dependencies] 或 install_requires 部分，以及本地路径依赖（ path = ../common-utils ）。
• 目录结构上，关注 src/ 布局、 app/ 目录、以及像 alembic/ （数据库迁移）这样的特定文件夹。
• 在规则文件中，可以加入：“使用Pydantic进行数据验证和设置管理”、“使用SQLAlchemy作为ORM层，遵循其声明式模式”、“异步IO使用 asyncio 和 httpx ”。

对于Go项目：

• 分析 go.mod 文件是关键，查看 module 名称和 require 块。Go的本地依赖通常通过 replace 指令或go workspace来管理，提示词需要指导AI识别这些模式。
• 关注标准的Go项目布局： cmd/ , pkg/ , internal/ , api/ 等目录的用途。
• 规则文件可以强调：“错误处理应使用 errors.Wrap 或 fmt.Errorf 并附带上下文”、“日志记录使用结构化的 log/slog ”、“配置管理使用Viper”。

对于混合栈工作区： 这是Context Builder最能体现价值的地方。你需要在提示词中明确告诉AI：“本工作区包含Node.js、Python和Go项目。请根据每种语言对应的项目特征文件进行分析。” 生成的 WORKSPACE_OVERVIEW.md 需要能清晰地说明不同语言服务之间的通信方式（如通过gRPC、REST API或消息队列）。

4.3 管理AI上下文与Token消耗的实战经验

运行一次Context Builder消耗的Token是巨大的，因为它需要读取大量文件内容、进行分析、并生成更大量的文档。以下是一些控制成本和确保成功运行的技巧：

1. 分而治之 ：如果你的工作区非常大（超过10个项目），一次性分析可能导致上下文窗口爆炸。可以尝试分批进行。首先，修改提示词的开头部分，将“分析所有项目”改为“仅分析 services/ 目录下的项目”。运行完成后，再修改为“分析 apps/ 目录下的项目”，并在后续提示中引用之前生成的概述文档，让AI知道已经分析过一部分了。
2. 排除无关目录 ：在提示词中明确指示AI忽略某些目录。例如：“在分析时，请忽略所有名为 node_modules 、 dist 、 build 、 .git 、 .next 的目录以及所有以点开头的隐藏文件。” 这能显著减少需要读取和处理的内容。
3. 使用“快照”模式 ：对于超大型项目，可以考虑先手动为每个项目创建一个简化的“项目描述卡片”（一个简单的 project-card.md ），包含项目名称、核心职责、主要技术栈和关键依赖。然后让AI基于这些卡片来生成详细的架构文档和关系图，而不是从零开始扫描所有文件。这需要前期人工介入，但能极大降低AI的负担。
4. 选择合适的模型 ：确保你使用的AI模型支持足够长的上下文。Claude 3.5 Sonnet（200K）、GPT-4 Turbo（128K）是较好的选择。对于非常大的工作区，甚至需要考虑使用具有100万以上上下文窗口的模型（如某些云服务商提供的特定模型）。
5. 关注输出截断 ：如果AI的输出在中间被截断，除了说“继续”之外，更有效的方法是定位截断位置。例如，如果输出停在了生成 project-2 的依赖图时，你可以回复：“我看到你正在生成 project-2 的Mermaid依赖图，但输出中断了。请从 project-2 的 DEPENDENCIES.md 文件的‘## 内部依赖’小节开始，继续完成这个文件，然后继续处理 project-3 。”

5. 常见问题排查与效能提升

在实际使用中，你肯定会遇到各种问题。下面是我遇到的一些典型情况及其解决方法。

5.1 问题排查速查表

问题现象	可能原因	解决方案
AI完全无法理解指令，或输出无关内容。	1. 提示词复制不完整，丢失了开头的关键指令。 2. AI会话历史混乱，干扰了当前任务。 3. 使用的AI模型能力不足（如使用了上下文窗口很小的模型）。	1. 重新从源文件完整复制提示词，在新会话中粘贴。 2. 开启一个全新的、干净的聊天会话。 3. 切换到更强大的模型，如Claude 3.5 Sonnet或GPT-4 Turbo。
AI分析过程卡住，或反复分析同一个项目。	1. 工作区目录结构过于复杂或存在循环软链接。 2. AI在解析某个损坏或格式奇特的文件时陷入循环。	1. 简化工作区结构，移除不必要的嵌套和链接。分批运行分析。 2. 在提示词中增加“如果遇到无法解析的文件，请跳过并记录在日志中，然后继续”的指令。
生成的依赖图不准确，漏掉了某些依赖。	1. 内部依赖未在包管理文件中显式声明（如使用了Monorepo工具如Turborepo、Nx，其依赖在根目录管理）。 2. 依赖是通过环境变量或动态配置加载的，AI静态分析无法发现。	1. 在运行前，确保AI有权限读取Monorepo根部的配置文件（如 turbo.json 、 nx.json ）。在提示词中特别指出需要分析这些文件。 2. 手动检查生成的 DEPENDENCIES.md ，补充AI遗漏的动态依赖关系。这是目前静态分析的局限性。
生成的规则文件（.mdc）过于笼统，没有针对性。	AI未能从代码中准确推断出团队的具体偏好和约定。	不要完全依赖AI推断。将生成的 .mdc 文件作为基础模板，然后手动编辑，加入你们团队的 具体 编码规范、必须使用的内部工具函数、禁止使用的废弃模式等。
运行过程消耗了巨额Token，费用很高。	工作区文件总量太大，AI读取了太多内容。	采用“分而治之”策略。先分析核心的、相互紧密依赖的项目子集。使用 .cursorignore 或类似机制（在提示词中声明）让AI忽略测试文件、图片、文档等非代码资源。

5.2 提升文档生成质量的技巧

1. 提供“种子信息” ：在运行元提示词之前，可以先给AI一些背景信息。例如，先发一条消息：“接下来我将请你分析一个电商平台的工作区，它包含微服务、前端应用和共享库。核心业务涉及用户、商品、订单和支付。” 这能给AI一个宏观框架，帮助它更好地理解各个项目的业务角色。
2. 定制化输出模板 ：如果你对生成的 ARCHITECTURE.md 格式不满意，可以直接修改 prompt.md 文件中关于文档模板的部分。比如，你的团队特别关注“性能指标”和“监控点”，你就可以在模板里加上“## 性能考量”和“## 监控与日志”这两个章节，引导AI在分析时去代码中寻找相关线索（如是否使用了 Prometheus 客户端、是否有特定的日志模块）。
3. 迭代优化 ：第一次生成的文档可能不完美。你可以把生成的结果作为新的上下文，给AI更具体的反馈。例如：“你为 user-service 生成的架构文档缺少了对消息队列（RabbitMQ）集成的描述。请重新分析该项目的代码，特别是 src/messaging/ 目录，并更新 ARCHITECTURE.md ，补充消息生产与消费的流程。” 通过这种多轮对话，可以不断精炼文档。
4. 人工审核与润色 ：永远记住，AI是强大的助手，但不是完美的作家。生成的所有文档都必须由资深开发者进行审核。检查技术栈描述是否准确、依赖关系是否完整、核心流程描述是否清晰。用人工的智慧弥补AI可能存在的理解偏差，并将业务层面的深层知识（比如“为什么选择A方案而非B方案”）补充进去。

5.3 处理复杂依赖与循环依赖

当项目间存在循环依赖（A依赖B，B又依赖A）时，AI生成的Mermaid图可能会标识出来，但更重要的是，你需要在实际的架构文档中强调这一点，因为这通常是一个设计上的“坏味道”。

在提示词中可以加入这样的指令： “如果在依赖分析中发现循环依赖（即项目A依赖于项目B，同时项目B也直接或间接依赖于项目A），请在相关项目的 DEPENDENCIES.md 文件顶部添加一个显著的警告区块（使用Markdown的 > **警告** 语法），明确指出循环依赖的存在，并简要说明这可能带来的问题（如构建困难、职责不清）。同时，在 WORKSPACE_OVERVIEW.md 中也要特别指出这一点。”

这样，生成的文档不仅能反映现状，还能起到架构预警的作用，推动团队去解耦这些模块。

最后，我想分享一点个人体会：Context Builder这类工具的价值，不仅仅在于产出那一堆Markdown文件。它的核心价值在于 迫使你和你的团队以一种机器可读、AI可理解的方式去思考和梳理你的系统架构 。这个过程本身就是一个极好的架构审视（Architecture Review）机会。在AI的辅助下，那些隐藏的、模糊的依赖关系被暴露出来，不一致的技术选择变得醒目。它从一个“文档生成工具”，变成了一个“架构治理的催化剂”。我建议每个季度或每次重大迭代后，都重新运行一次，看看你的系统“地图”发生了哪些变化，这或许是保持代码库健康最省力也最智能的方法之一。