上下文工程实战：让 AI 理解大型 monorepo 的分层

上下文工程实战让 AI 理解大型 monorepo 的分层一、monorepo 给 AI 出的难题大型 monorepo 里包与包层层依赖。一个需求要改五六个包跨十几层目录。把整个仓库塞给模型窗口早爆了。更麻烦的是分层关系。底层工具包、中层业务包、上层应用包各有边界。模型若不懂分层可能在上层直接改底层破坏封装。让 AI 理解 monorepo 的分层是上下文工程的高阶题。本文探讨如何把仓库结构翻译成模型能用的上下文。二、分层上下文的构建机制核心是把结构知识显式喂给模型。不是丢源码而是丢地图包清单、依赖方向、公开 API、改动的合理边界。模型据此知道该改哪层、不该越界。再按需展开具体文件而非全量载入。下面是分层上下文的构造flowchart TD A[monorepo 结构] -- B[抽取包清单依赖图] B -- C[生成分层地图文本] C -- D[拼接为系统提示] D -- E[用户请求相关包展开] E -- F[LLM 在边界内生成] style C fill:#e1f5fe style F fill:#e8f5e9关键在地图先行代码后展。先用结构约束范围再展开细节。避免模型在不知全貌时乱改。三、生产级实现下面用代码描述分层地图的生成。from dataclasses import dataclass from pathlib import Path from typing import dict dataclass class Package: name: str layer: str # base / biz / app depends_on: list[str] def build_map(packages: list[Package]) - str: 把 monorepo 分层压成模型可读的地图文本 lines [# 仓库分层地图] by_layer: dict[str, list[Package]] {} for p in packages: by_layer.setdefault(p.layer, []).append(p) order [base, biz, app] for layer in order: lines.append(f## {layer} 层) for p in by_layer.get(layer, []): deps ,.join(p.depends_on) or 无 lines.append(f- {p.name} (依赖: {deps})) return \n.join(lines) def allowed_target(layer: str) - set[str]: # 上层可改下层下层不可反向改上层 rules {base: {base}, biz: {base, biz}, app: {base, biz, app}} return rules.get(layer, set()) if __name__ __main__: pkgs [ Package(utils, base, []), Package(order, biz, [utils]), Package(web, app, [order]), ] print(build_map(pkgs))真实系统会从workspace配置与package.json自动抽包。并标记公开 API 边界让模型知道哪些能改、哪些只能调用。四、上下文工程实战的代价与边界分层上下文有用但有前提。结构抽取的准确度。依赖图抽错地图就误导模型。应基于真实的依赖声明而非目录猜测。并定期刷新反映重构后的新结构。地图与代码的同步。地图过时模型按旧分层改踩坑。结构变更时要同步更新上下文源。可接 CI 校验地图与声明一致。边界限制的软硬。强限制模型不准改某层可能误伤合理改动。应区分硬边界公开 API 不可破与软建议优先改本层。硬边界进门禁软建议进提示。大 monorepo 的尺度。包上千时地图本身也长。应分层级展开先给顶层地图按需下钻。避免地图比代码还占窗口。分层上下文的边界冲突处理要预案。现实里模型可能合理越界比如为修上层 bug 必须动底层工具函数。此时硬禁止会卡住合理改动。建议区分硬边界公开 API 契约不可破、跨团队接口不可擅自改与软建议优先改本层硬边界进门禁拦截软建议进提示引导。另一个实践是依赖方向校验用 lint 或构建规则禁止上层反向依赖下层实现细节从机制上固化分层而非只靠上下文提示。最后分层地图要随重构更新结构变了地图不变模型又会按旧认知改错地方。五、总结让 AI 理解 monorepo本质是把结构知识显式化。机制上先抽分层地图约束范围再按需展开代码。工程上保证地图与依赖声明同步、边界分软硬。落地路线先从依赖声明抽包与分层生成地图文本进系统提示标记公开 API 硬边界按需下钻展开。模型懂分层改动才不越界。