企业官网建设流程全解析

用 CLAUDE.md 上下文文件加速 AI 编码：Lightdash 仓库 add-context-file 命令规范深度解析

【免费下载链接】lightdashAgentic BI. Analytics at the speed of code ⚡️项目地址: https://gitcode.com/GitHub_Trending/li/lightdash

导读：本文基于 Lightdash 开源仓库的自定义 Claude Code 命令.claude/commands/add-context-file.md，系统讲解"目录级 CLAUDE.md 上下文文件"的生成规范——包括 XML 标签结构、内容编写原则、文件链接语法与格式化检查。读完本文，你将掌握如何在大型 monorepo 中为每个模块目录产出 50–100 行、可被 AI 编码助手快速消费的最小上下文文件，并理解 Lightdash 仓库中 60+ 个 CLAUDE.md 文件背后的统一约定。

一、背景：为什么大型仓库需要目录级上下文文件

Lightdash（Agentic BI，以代码速度做分析的开源项目）是一个庞大的 pnpm monorepo，包含packages/backend、packages/frontend、packages/common、packages/cli、packages/warehouses等多个工作区，仅 backend 就划分出 controllers、services、models、database、scheduler 等几十个模块目录。当 AI 编码助手面对这样一个仓库时，单一根级CLAUDE.md（仓库根 CLAUDE.md）只能给出全局架构指引，而每个具体模块的使用方式——比如"controllers 层怎么注册路由""services 层如何通过 ServiceRepository 做依赖注入"——如果散落在源码里，AI 需要反复跳转阅读才能摸清。

为此，Lightdash 在.claude/commands/下维护了一套自定义斜杠命令（add-context-file、aks-dev、cs-bugs、docker-dev、k8s-dev等），其中add-context-file.md定义了"为某个目录生成 CLAUDE.md 上下文文件"的标准流程。它的目标非常明确：

The purpose of the context file is to make it as fast as possible to understand how to use the files in this module.

即：上下文文件的存在意义，是让工程师（以及 AI）以最快速度掌握该模块内文件的使用方法，而不是把文档写成详尽的源码注释。

二、命令概览：add-context-file 的工作方式

add-context-file.md的第一行定义了这个命令的本质行为：

Add a CLAUDE.md context file in the directory $ARGUMENTS

这是一个典型的 Claude Code 自定义命令（slash command）模板：用户在对话中输入/add-context-file <目标目录>，$ARGUMENTS会被替换为实际传入的目录路径，Claude 依据后续<format>、<content>、<linting>三段规范，在该目录下创建或更新CLAUDE.md文件。

命令模板由三个部分组成：

需要说明的是，add-context-file的产物是目录级 CLAUDE.md，它与仓库根级CLAUDE.md的分工不同：根级文件描述全局架构、开发命令、跨模块约定（如根 CLAUDE.md 中的 Runtime Services 架构表、feature flags、release-safety 声明）；而目录级文件只聚焦"这个目录怎么用"。例如 docs/CLAUDE.md 就只回答"什么时候该在 docs 下建文档、命名与结构标准是什么"，packages/common/src/authorization/CLAUDE.md 则定位为"authorization 目录的地图"，明确指出"TypeScript 文件才是事实来源，本文档是给 Agent 的地图"。

三、格式规范：用 XML 标签替代 Markdown 标题

add-context-file最显著的约定是：上下文文件使用 XML 标签组织章节，而不是 Markdown 的#/##标题。这是为了给 AI 提供结构明确的语义化区块，便于解析与检索。

3.1 允许的五个标签

值得注意的是，<importantToKnow>的定位很精确：不需要覆盖所有业务规则，但必须指出任何关键业务逻辑、约束、gotcha、或代码本身看不出来的东西。这正是"最小可行上下文"的边界。

3.2 代码块、图表与链接的语法

• 代码块：使用带语言标识的三重反引号，如```typescript、`@packages/backend/src/controllers/baseController.ts @packages/backend/src/controllers/authentication/index.ts @packages/backend/src/controllers/v2/ @docs/account-patterns.md

这种语法对 Claude Code 而言是可直接打开的文件引用，比裸路径更利于 AI 跳转阅读。 ### 3.3 行数约束：50–100 行 格式规范明确要求 **Keep files between 50 and 100 lines**。这是刻意设计的"信息密度红线"：文件太短说明上下文不足，太长则违背"易于理解且有用，但不完整"的初衷。从仓库实际产物看，这一约束得到了执行：`packages/backend/src/database/CLAUDE.md` 约 80 行，`packages/frontend/src/features/sqlRunner/CLAUDE.md` 约 91 行，`packages/common/src/templating/CLAUDE.md` 约 105 行，个别文件会小幅突破但整体保持在百行级别。 ## 四、内容编写原则：指导性而非详尽 `<content>` 区块给出了六条具体的内容准则，这是写好上下文文件的核心方法论： 1. **提供模块目的与价值的快速总结，不纠缠实现细节**——`<summary>` 一两句话讲清"这是什么、为什么存在"。 2. **解释关键接口、入口点、导出的函数，并配简要用法示例**——`<howToUse>` 是文件的主体。 3. **代码示例只需覆盖最常见用法**，不需要覆盖所有参数或边界情况——"It must be instructive, not exhaustive." 4. **不要解释模块的内部实现细节**——`<importantToKnow>` 只记录"不读代码就看不出来"的东西。 5. **有选择地标注关键业务逻辑/约束/gotcha**，而不是罗列全部业务规则。 6. **能链接就链接，不要复制**——外部文档、spec、教程一律以链接形式给出；涉及复杂工程概念时链接到教程，让工程师按需深入学习。 以 [services/CLAUDE.md](https://link.gitcode.com/i/2e82e5957944dab581b435a9ba5893a6) 为例，它的 `<importantToKnow>` 没有复述每个服务的代码，而是提炼了四条"源码里不明显"的约定：参数类型契约（`UuidOrSlug` 必须解析为 `entity.uuid` 后才能下游使用）、账号模式（方法应接收 `account: RegisteredAccount` 而非 `user: SessionUser`）、日志约定（用 `this.logger` 而非直接 import Logger）、注册要求（新增 service 必须登记进 ServiceRepository.ts）。这些内容直接决定 AI 写出正确代码，却需要通读大量源码才能总结出来——这正是上下文文件的价值所在。 再比如 [QueryBuilder/CLAUDE.md](https://link.gitcode.com/i/75176c49e100c12b4c0d82a9e0f8b4fd) 的 `<summary>` 用一个反直觉的事实开篇："PivotQueryBuilder 并不做数据透视——它只生成给每行打上 `row_index`/`column_index` 标签的 SQL，真正的透视发生在下游的 AsyncQueryService"，并明确"本文件只覆盖 SQL 生成，端到端透视管线见 [docs/pivoting.md](https://link.gitcode.com/i/9d8d2ec9953f1429b286edf768313eef)"。这种"范围声明 + 反直觉提示 + 外部链接"的组合，是上下文文件高信息密度的关键。 ## 五、真实生态：Lightdash 中的 CLAUDE.md 文件矩阵 `add-context-file` 命令并非停留在规范层面，它在 Lightdash 仓库中已经产出了 **65 个 `CLAUDE*.md` 文件**，形成了三级上下文体系： **第一级：仓库根级** - [CLAUDE.md](https://link.gitcode.com/i/04f95781d3348e93f3f46349c5551de2)——全局架构、开发命令、代码风格、安全实践、发布安全声明等。 - [CONTEXT-MAP.md](https://link.gitcode.com/i/3bb0c8c8cdf04f6abb45ddf4d1323363)——跨特性领域的领域术语表索引（Data apps、Chart types、Pre-aggregates、AI agent 等），要求写代码/文档/UI 文案前先读对应词表，使用规范术语、禁用 `_Avoid_` 别名。 **第二级：包/模块级（add-context-file 的主战场）** - backend：`src/controllers`、`src/services`、`src/models`、`src/database`（含 `migrations`、`entities`、`seeds/development` 子目录）、`src/scheduler`、`src/routers`、`src/utils/QueryBuilder` 等各有一份。 - frontend：`src/components/common/Filters`、`src/components/common/PivotTable`、`src/features/sqlRunner`、`src/features/dashboardFilters`、`src/ee/features/embed` 等。 - common：`src/authorization`（含 `space` 子目录）、`src/templating`。 - cli、e2e、api-tests、query-sdk、docker、docs、scripts、sandboxes、agent-harness 等顶层目录也各自覆盖。 **第三级：跨目录引用关系**——目录级文件之间会互相引用，形成可导航的上下文网络。例如根 [CLAUDE.md](https://link.gitcode.com/i/04f95781d3348e93f3f46349c5551de2) 在讲 release-safety 时指向 [migrations/CLAUDE.md](https://link.gitcode.com/i/e780e7c577289000bfff1521c571ee6d) 的 `#release-safety-declarations` 锚点；controllers 的 CLAUDE.md 在讲账号模式时链接 [docs/account-patterns.md](https://link.gitcode.com/i/49577171923913002e1a3d18129a8e07)。这种"根文件不重复模块细节、只做链接分发"的做法，与 `add-context-file` 中"链接到外部文档而非重复"的准则一脉相承。 从源码结构看，目录级 CLAUDE.md 与 `.claude/skills/` 下的技能文件（`add-onboarding-tour`、`deprecate-endpoint`、`ld-permissions`、`frontend-style-guide` 等）是两套互补机制：技能文件承载**可执行的流程步骤**，上下文文件承载**模块的静态使用知识**。比如 [controllers/CLAUDE.md](https://link.gitcode.com/i/50af716552b7f5092cdb6eb8697a9f85) 中关于端点废弃的部分会指向 `deprecate-endpoint` 技能获取完整操作模式。 ## 六、质量检查：pnpm format 与排版细节 `<linting>` 区块规定了两条产出后的强制检查：

• After writing the CLAUDE.md file, runpnpm formaton that single file to ensure proper formatting.
• Add a line break between tag and the code block.

第一条要求对新建的 CLAUDE.md **单独执行 `pnpm format`**。在 Lightdash 仓库中，根 [package.json](https://link.gitcode.com/i/e6caa6569d53a56efaec39b9dd76c7ce) 的 `format` 脚本由 `turbo run format` 驱动，作用于 `@lightdash/common`、`backend`、`@lightdash/frontend` 等工作区；命令规范强调"on that single file"，即只格式化新产出文件，避免波及整个仓库。这一步骤确保 XML 标签结构、代码缩进与 Markdown 排版符合仓库的 Prettier 配置。 第二条是排版细节：`<codeExample>` 标签与其后的代码块之间必须有一个空行。从仓库实际文件看，这一约定被严格执行——[services/CLAUDE.md](https://link.gitcode.com/i/2e82e5957944dab581b435a9ba5893a6) 中 `<codeExample>` 与首个 ` ```typescript ` 之间均有空行，[QueryBuilder/CLAUDE.md](https://link.gitcode.com/i/75176c49e100c12b4c0d82a9e0f8b4fd) 同样如此。空行缺失会导致部分 Markdown 渲染器把代码块误判为标签内容的一部分，破坏文档的可读性。 ## 七、实战要点总结 综合命令规范与仓库落地实践，生成一份合格目录级 CLAUDE.md 的检查清单如下： 1. **定位**：文件只服务于"该目录怎么用"，不重复根级架构、不解释模块内部实现。 2. **结构**：严格使用 `<summary>` / `<howToUse>` / `<codeExample>` / `<links>` / `<importantToKnow>` 五个标签；确实需要讲解复杂流程时用 ` ```mermaid ` 画图。 3. **内容**：summary 一句话讲清模块价值；howToUse 讲清入口点与最常见用法；importantToKnow 只收录源码里看不出的业务约束与陷阱。 4. **示例**：代码示例可直接复制运行，但只覆盖主要用法，不穷举参数。 5. **链接**：仓库内引用一律用 `@/path` 语法，避免在文件内粘贴大段外部文档。 6. **篇幅**：控制在 50–100 行。 7. **检查**：写完后单独对该文件执行 `pnpm format`，并确认 `<codeExample>` 与代码块之间有空行。 这套规范的价值在于：它把一个本来完全依赖个人发挥的"写文档"任务，变成了 AI 可重复执行的确定性流程，同时通过行数上限与"指导性而非详尽"的原则，强制上下文文件保持高信息密度——这正是 Lightdash 能够在 60 多个模块目录上维持统一、可维护的 AI 上下文体系的关键。对于任何想要为自己的大型代码仓库建立 AI 编码上下文层的团队，`.claude/commands/add-context-file.md` 都是一份可以直接借鉴的模板。

【免费下载链接】lightdashAgentic BI. Analytics at the speed of code ⚡️项目地址: https://gitcode.com/GitHub_Trending/li/lightdash