面向 LLM 与 Agent 的源码文档工程：effect-smol 的 ai-docs 体系与 LLMS.md 生成机制

面向 LLM 与 Agent 的源码文档工程effect-smol 的 ai-docs 体系与 LLMS.md 生成机制【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code导读本文聚焦于 effect-smol 仓库Effect 库及其相关包的开源实现中一套独特的「AI 文档ai-docs」工程实践它把面向人类与面向 LLM/Agent 的文档分离以ai-docs/src为唯一内容源通过pnpm ai-docgen自动生成可供 AI 上下文注入的LLMS.md再借助 copy-ai-docs.mjs 把同一份文档分发到每个 npm 包内。读完本文你将掌握这套文档生成管线的目录约定、源文件规范、示例编写准则、再生成命令以及它如何让每一个发布包都自带面向 LLM 的文档能力——这套方法论可直接迁移到任意需要「让 Agent 快速读懂代码库」的开源项目中。一、文档定位LLMS.md 是 ai-docs/src 的编译产物ai-docs本身是一个独立的私有 npm 工作区包其依赖全部来自仓库内的 workspace 包effect、effect/ai-*、effect/sql-*、effect/platform-*等见 ai-docs/package.json。该目录下的 README.md 开宗明义地定义了数据流LLMS.mdis generated fromai-docs/src.也就是说仓库根目录的 LLMS.md 不是手写的而是由ai-docs/src下的所有内容拼接、渲染生成的产物。LLMS.md这个名字本身即暗示其目标读者LLM System大语言模型系统——即供 Claude、GPT 等 Agent 在读取仓库时优先注入的上下文文件。从 LLMS.md 的实际内容看它包含 20 余个主题章节覆盖 Effect 核心Effect.gen/Effect.fn、Schema 领域建模、Service 与 Layer、错误处理、资源与 Scope、运行时、PubSub、Stream 流处理、ManagedRuntime 集成、RequestResolver 批处理、Schedule 调度、DateTime、可观测性、effect/vitest测试、SQL、HttpClient、HttpApi、子进程、CLI、AI 模块与 cluster 分布式编程——几乎与仓库内的包结构一一对应。二、如何新增文档内容三步工作流README 给出了向文档体系添加内容的完整流程在ai-docs/src/**/index.md中添加或更新该章节的导语文本在同一目录下以.ts文件形式添加代码示例运行pnpm ai-docgen重新生成LLMS.md。这种「导语index.md 可运行示例.ts」的双文件模式保证了每个章节既有概括性说明又有真实可编译的代码证据而不是空泛的 API 罗列。以 ai-docs/src/index.md 为例它是整个文档的开篇说明了文档的适用范围并特别强调了一条对 Agent 的约束示例中的注释仅为教学说明实际代码中不应包含这些注释。章节结构实例以01_effect目录为例其物理布局与最终LLMS.md的章节严格对应ai-docs/src/01_effect/ ├── 01_basics/ # index.md 01_effect-gen.ts 02_effect-fn.ts 10_creating-effects.ts ├── 02_schema/ # index.md 10_schema-basics.ts ├── 03_services/ # index.md 01_service.ts 10_reference.ts 20_layer-composition.ts 20_layer-unwrap.ts ├── 04_errors/ # index.md 01_error-handling.ts 10_catch-tags.ts 20_reason-errors.ts ├── 05_resources/ # index.md 10_acquire-release.ts 20_layer-side-effects.ts 30_layer-map.ts ├── 06_running/ # index.md 10_run-main.ts 20_layer-launch.ts └── 07_pubsub/ # index.md 10_pubsub.ts例如 01_basics/10_creating-effects.ts 演示了从纯值、同步副作用、可能抛错的同步代码、Promise API、可空值到回调式 API 等六种 Effect 构造方式06_running/10_run-main.ts 则展示了NodeRuntime.runMain与BunRuntime.runMain作为进程入口的用法。三、源文件约定可排序、可渲染、可忽略README 对ai-docs/src下的文件规定了三条硬性约定1. 数字前缀控制顺序使用数字文件名前缀控制渲染顺序如10_、20_、30_数字越大越靠后避免以0开头除非被明确要求——因为以 0 开头容易在排序、glob 匹配与某些工具链中产生意外行为如被误当作八进制或无法正常排序。这一约定保证了章节与示例的稳定次序不依赖文件系统的不可靠默认排序。2. 顶层 JSDoc 块控制标题与描述每个示例.ts文件通过文件顶部的 JSDoc 块声明渲染后的标题与描述/** * title Creating effects from common sources * * Learn how to create effects from various sources, including plain values, * synchronous code, Promise APIs, optional values, and callback-based APIs. */ import { Effect, Schema } from effect其中title会直接成为LLMS.md中的链接标题描述文字则作为该条目的说明。在 10_creating-effects.ts 中可以看到这种模式title声明标题随后两行描述其教学范围。最终渲染进LLMS.md的效果即类似- **[Creating effects from common sources](https://link.gitcode.com/i/f6b0277ba6ee357256ecb2f483af6501)**: Learn how to create effects from various sources, including plain values, ...3. fixtures 目录被忽略fixtures目录在生成时被整体忽略不进入最终文档。其用途是存放示例所需的支撑代码与数据——例如建议的项目目录结构、服务拆分示例等。这样既保持了示例文件的聚焦又提供了「真实工程骨架」的教学素材而不会污染生成的文档正文。四、示例编写准则真实、服务化、带教学注释README 用两个「必须」和两个「倾向」规定了示例代码的编写标准两个必须所有代码示例必须有充分注释解释代码的「为什么」而不仅是「做什么」目标是教会读者使用 API代码必须代表真实世界的用法与最佳实践禁止写不具代表性的玩具示例。两个倾向优先使用 service 风格组织代码因为这是真实世界的主流用法使用fixtures目录来示范项目结构、文件组织与代码组织的最佳实践。以 LLMS.md 中的核心示例为例可以看到这些准则的具体落地// 用 Effect.gen 以类 async/await 的命令式风格编写yield* 获取 Effect 的结果 Effect.gen(function*() { yield* Effect.log(Starting the file processing...) return yield* new FileProcessingError({ message: Failed to read the file }) }).pipe( // 用 .pipe 追加额外行为 Effect.catch((error) Effect.logError(An error occurred: ${error})), Effect.withSpan(fileProcessing, { attributes: { method: Effect.gen } }) ) // 用 Schema.TaggedError 定义带结构化字段的领域错误 export class FileProcessingError extends Schema.TaggedErrorFileProcessingError()( FileProcessingError, { message: Schema.String } ) {}服务定义部分则示范了「Context.Service 静态 Layer Effect.fn实现」的标准组合export class Database extends Context.ServiceDatabase, { query(sql: string): Effect.EffectArrayunknown, DatabaseError }()(myapp/db/Database) { static readonly layer Layer.effect( Database, Effect.gen(function*() { const query Effect.fn(Database.query)(function*(sql: string) { ... }) return Database.of({ query }) }) ) } export type DatabaseService Database[Service]错误处理章节则展示了Effect.catchTag多错误合并捕获与Effect.catch兜底的分层恢复策略。此外 README 还包含一条工程治理规则仅含 ai 文档变更的 Pull Request 无需附带 changeset——文档不改变任何包的行为因此不需要版本变更记录。五、再生成命令与分发机制再生成命令命令作用pnpm ai-docgen一次性从ai-docs/src重新生成LLMS.mdpnpm ai-docgen:watch监听模式源文件变化时自动再生成分发到每个包的实现机制LLMS.md生成之后还要进入每个发布包的制品中。copy-ai-docs.mjs 负责完成这一分发用 glob 匹配所有packages/{*,*/*}/package.json跳过private包校验每个包的files字段必须包含AGENTS.md、CLAUDE.md与ai-docs/**/*否则直接抛错——从机制上强制每个发布包都携带 AI 文档将根目录LLMS.md复制为包内的AGENTS.md与CLAUDE.md分别服务 GitHub Copilot 与 Claude 等 Agent 工具将ai-docs目录整体复制到包内并用includeAiDocs过滤器排除dist与node_modules。这意味着每个安装effect或effect/*包的开发者其 Agent 都会在node_modules中直接拿到一份面向 LLM 的完整使用文档无需再跳转外部站点。这与 LLMS.md 开篇「优先使用本仓库文档与源码避免过时或错误的外部副本」的指引形成了闭环。六、可供借鉴的文档工程方法论从这套体系中可以提炼出对任何开源项目都可复用的要点单一内容源多形态产物一份ai-docs/src同时产出LLMS.md、各包AGENTS.md、CLAUDE.md避免多份文档漂移用机器可读的约定替代口头规范数字前缀排序、titleJSDoc、fixtures忽略规则全部是可校验的硬性约束copy-ai-docs.mjs甚至在打包时强制校验files字段示例即文档的证据每个知识点都配可运行的.ts示例且要求注释解释「为什么」这正是 LLM 最需要的上下文密度面向 Agent 的文档独立于面向人的文档ai-docs专注生成 Agent 上下文与人用的 API Reference 各司其职。结语effect-smol 的ai-docs体系回答了现代开源项目的一个现实问题如何让 LLM 与 Agent 以最低成本、最准确的方式理解代码库。它用「源码目录 生成命令 打包校验」的组合把文档质量变成工程规范而非自觉行为。对于正在维护大型 TypeScript 项目、或希望提升仓库对 AI 工具友好度的开发者ai-docs/README.md 与其配套的 LLMS.md、copy-ai-docs.mjs 是一套可直接落地参照的完整范本。【免费下载链接】t3code项目地址: https://gitcode.com/GitHub_Trending/t3/t3code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考