Homebrew 文档维护实战docs/AGENTS.md 写作规范与校验工作流解析【免费下载链接】brew The Package Manager for Everywhere项目地址: https://gitcode.com/GitHub_Trending/br/brewdocs/AGENTS.md是 Homebrew/brew 仓库为文档贡献者无论人还是 AI Agent编写的操作说明它把 docs 站点维护的工具链选择、Markdown 写作风格和四层校验命令固定成一套可执行规范。本文围绕该文档展开结合 .github/workflows/docs.yml、docs/Rakefile、docs/Gemfile 与 Vale 风格库等仓库实况说明如何在本地复现与 Homebrew 官方一致的文档校验流水线。读完你将掌握一套从写作到 lint、到断链检查、再到 CI 发布的完整方法可以直接套用到任何 Jekyll 驱动的大型文档站点维护中。一、文档定位一份写给人与 AI Agent 的维护说明书docs/AGENTS.md带 Jekyll 前置元数据last_review_date: 2026-06-10标题为 Agent Instructions for Homebrew/brew docs开篇即限定适用范围These instructions apply when working indocs/。也就是说它是一份作用于目录边界的约定文档凡是在docs/目录下增删改文档都应遵守其规则。之所以需要这样一份说明是因为 Homebrew 的文档站点并非手写 HTML而是基于 Jekyll 静态站点工具链见 docs/_config.yml从几十篇 Markdown 生成 docs.brew.sh 等另有渠道。一个容易被忽略的细节是docs/_config.yml 的exclude列表中明确排除了AGENTS.md同时被排除的还有Gemfile*、Rakefile、vale-styles等工程性文件。这印证了 AGENTS.md 的定位它面向编辑者而不是读者不会被 Jekyll 构建成公开页面而是与仓库根目录的 AGENTS.md、CLAUDE.md 一脉相承作为人类协作者与 AI 编程助手共同的进场须知。从内容结构看这份文档由四部分组成下文逐一展开部分解决的问题Tooling用什么命令跑 docs 工具链、为什么不用./bin/brewMarkdown style文档写作的排版、拼写与链接规范Verification改完文档后本地要跑哪些校验Notes站点构建、Rake 任务与 manpage 再生成的补充约定二、工具链用brew bundle exec管理 docs 的 Ruby 环境AGENTS.md 的 Tooling 部分给出了三条关键约定直接决定了 docs 目录下所有命令的形态从docs/目录使用系统级 Homebrew 的brew bundle exec ...工作流而不是./bin/brew。原因在于 docs 站点是一个独立的 Ruby/Jekyll 项目依赖定义在 docs/Gemfile并不需要 brew 本体自举运行用brew bundle拉起的 Bundler 环境最贴近官方 CI.github/workflows/docs.yml 同样用bundle exec rake ...形式执行任务。所有校验命令都设置HOMEBREW_NO_AUTO_UPDATE1避免 brew 在跑校验时先触发自身自动更新从而与 CI 环境保持一致、加快反馈速度。这一点在 .github/workflows/docs.yml 的环境变量中同样成对出现另有HOMEBREW_DEVELOPER、HOMEBREW_NO_ENV_HINTS等。用brew bundle exec bundle install安装或刷新文档 Ruby 环境。docs/下存在 Brewfile 与 Gemfile前者描述 brew 侧需要的东西后者声明 Jekyll 及其插件。以 Ruby 侧为例docs/Gemfile 精确刻画了工具链的组成这也是我们理解后续每条校验命令的前提构建侧jekyll及插件组其中jekyll-relative-links负责把文档里的.md相对链接在渲染时解析为最终页面 URL这正是写链接只写文件名能成立的底层机制jekyll-seo-tag、jekyll-sitemap、jekyll-titles-from-headings等负责 SEO 元数据。文档侧yard与yard-sorbet对应 Rakefile 里从 Ruby 源码生成 YARD API 文档的任务。测试侧html-proofer断链与 HTML 合法性检查、mdlMarkdownlint、rake。典型的首次环境准备命令为# 在 docs/ 目录下执行 HOMEBREW_NO_AUTO_UPDATE1 brew bundle exec bundle install需要说明的是docs/下并没有现成的可执行文件bin/jekyll这类调用依赖 Bundler 对本地 binstub 或 gem 内可执行文件的解析brew bundle exec的职责就是保证解析发生在 Bundler 锁定的版本上。若你只是快速预览文档效果CI 中使用的等价路径是bundle exec rake build见 docs/Rakefile。三、写作规范文档风格的可机械化约束AGENTS.md 的 Markdown style 部分总结了 Homebrew 文档的排版底线每一句几乎都能在仓库的工具配置或样式指南里找到落点。下面是逐条解读与仓库佐证。3.1 语义换行与表格对齐每句话独占一行semantic line breaks而不是按固定列宽回行。这样 diff 只影响改动的句子review 时更干净。这条规范在 docs/Prose-Style-Guidelines.md 的 One sentence per source line in Markdown, without wrapping prose to a fixed width 中被再次确认。Markdown 表格要用空格补齐列宽让源文件里|竖线肉眼可对齐。虽然渲染结果一样但对协作审阅极其友好。3.2 拼写英式拼写与 licence / license 的语义分工全文使用英式拼写与标点。名词用licence动词用license但当指代确切接口名时保留原样license——例如 Formula DSL 中的license方法、命令行选项。仓库里 docs/Licence-Guidelines.md 一整篇都在讨论如何在现实语境下区分二者AGENTS.md 只是把结论收敛成一条可执行规则。3.3 标点与列表避免 em-dash破折号改用分号、冒号与逗号。不使用 Oxford comma牛津逗号。嵌套无序列表缩进 2 个空格。这两条均有工具背书。Vale 样式库 docs/vale-styles/Homebrew/OxfordComma.yml 会在正文中捕捉牛津逗号而 docs/index.mdl_style.rb 的rule MD007, indent: 2正是为无序列表缩进量身定制的 Markdownlint 配置。注意同文件中exclude_rule MD013关闭了行宽检查正是为了让每句一行的规范不被行宽规则误伤。3.4 链接与 URL禁止裸 URL一律使用 Markdown 链接。站内链接必须指向.md文件本身例如[Bottles](https://link.gitcode.com/i/20272004a445d48f7effe4666f2581a3)而不是docs.brew.sh的成品 URL。这背后的技术原因是jekyll-relative-links插件会在构建时把这些相对 Markdown 路径自动解析成站点内页面把链接写成.md还让仓库内浏览如 GitHub 代码视图也能直接跳转。按仓库根路径换算AGENTS.md 中示例Bottles.md实际指向 docs/Bottles.md。文档站点中这类相对链接在源文件里全部是文件名 .md的形式。四、校验工作流四类检查本地全量复现AGENTS.md 强调修改文档后应运行 .github/workflows/docs.yml 与 docs/Rakefile 中相关的检查。以下命令均以docs 目录为工作目录执行除明确注明仓库根的之外。4.1 环境与构建HOMEBREW_NO_AUTO_UPDATE1 brew bundle exec bundle install HOMEBREW_NO_AUTO_UPDATE1 brew bundle exec bin/jekyll build第一条确保依赖齐全第二条本地构建站点是后续 lint/test 的先决条件。docs/Rakefile 中rake build就是对bundle exec jekyll build的封装CI 正是通过bundle exec rake build.github/workflows/docs.yml执行的。4.2rake lintMarkdownlint 与元数据完整性HOMEBREW_NO_AUTO_UPDATE1 brew bundle exec bundle exec rake lintrake lintdocs/Rakefile实际做了两件事对git ls-files *.md追踪的文档跑mdl但排除Manpage.md与站点首页index.md首页单独使用 docs/index.mdl_style.rb 这份更宽松的规则它豁免了行宽、标题层级、裸 URL 等规则并把 MD007 缩进固定为 2。检查每个.md文件是否都带last_review_date前置元数据——这就是为什么 docs/AGENTS.md 自身顶部也有last_review_date: 2026-06-10。4.3rake testHTMLProofer 断链与结构检查HOMEBREW_NO_AUTO_UPDATE1 brew bundle exec bundle exec rake testrake testdocs/Rakefile会先构建站点再用html-proofer检查_site/产物重点包括4 线程并行、自定义 User-Agent兼容 403/429 反爬、校验 favicon 与 OpenGraph 标签、强制 HTTPS、并针对 GitHub 等外部 URL 配置一天缓存。因此它既能发现仓库内.md链接失效也能发现外部链接返回 404/403/429。在 CI 中该步骤只在 pull request 上执行并失败重跑一次.github/workflows/docs.yml因为每次全量外部检查成本较高。4.4 Vale 文案检查与 RuboCop 代码块风格AGENTS.md 明确要求在仓库根目录额外执行两条内容变更类检查rg --files docs -0 -g *.md -g !vendor/** -g !_site/** -g !rubydoc/** | xargs -0 vale HOMEBREW_NO_AUTO_UPDATE1 brew style docs第一条先把docs/下所有 Markdown排除构建产物与 vendor以 NUL 分隔喂给 Vale。Vale 的规则由 .vale.ini 指定样式路径为./docs/vale-styles同时适用于*.md与*.rb启用Homebrew样式集合。这一集合即 docs/vale-styles/Homebrew 下的多个 YAML 规则文件例如Terms.yml把Pull Request纠正为pull request、Rubocop纠正为RuboCop、非上下文的MacOS纠正为macOS、ruby纠正为Ruby。OxfordComma.yml拦截牛津逗号。另有 Headings.yml标题大小写、Spacing.yml空格等构成了一套可自动执行的风格约束层是人写规范 机器兜底的典型实践。第二条brew style docs用 RuboCop 检查文档中嵌入的 Ruby 代码块是否符合仓库的代码风格对应 CI 中的 Check code blocks conform to our Ruby style guide 步骤.github/workflows/docs.yml。4.5 manpage 与补全的联动再生成AGENTS.md 的 Notes 部分最后提醒当文档改动依赖 manpage 或补全脚本的更新时需要先运行brew generate-man-completions --no-exit-code在官方 CI 中这一步位于 Cleanup Homebrew/brew docs 步骤.github/workflows/docs.yml即对 Homebrew/brew 本体仓库在跑 Vale 之前先重新生成manpages/brew.1与 shell 补全--no-exit-code保证生成结果差异不阻断主流程。实现入口可参考 Library/Homebrew/cmd/generate-man-completions.rb。五、本地校验与 CI 的映射关系把 AGENTS.md 给出的本地命令与 .github/workflows/docs.yml 的 docs job 对照能清晰看到这套工作流的设计哲学让本地开发者/Agent 跑与 CI 完全一致的命令把提交后才被 CI 打回的概率降到最低。本地校验docs/ 下CI 对应步骤检查目标brew bundle exec bundle installSetup Rubybundler-cacheRuby 依赖就绪brew bundle exec rake lintCheck Markdown syntaxMarkdownlint last_review_datebrew style docsCheck code blocks…文档中 Ruby 代码块风格rake buildjekyll buildBuild the site站点可构建rake testCheck for broken links仅 PRHTMLProofer 断链检查rg ... \| xargs -0 valeInstall Vale vale docs/英式拼写、术语、逗号等文案brew generate-man-completionsCleanup Homebrew/brew docsmanpage 与补全同步此外针对 Homebrew/brew 本体CI 在全部检查通过后还会执行rake yard从Library/Homebrew的 Ruby 源码重新生成 YARD API 文档docs/Rakefile.github/workflows/docs.yml并最终把_site/作为 GitHub Pages 产物上传部署。部署失败时还会自动开/关 GitHub issue.github/workflows/docs.yml形成构建-检查-部署-告警的完整闭环。六、可复用的实践清单把 docs/AGENTS.md 的方法论抽象出来任何维护 Jekyll 类文档仓库的团队都可以照搬这套分工写一份只面向编辑者的 AGENTS 说明并确保它被 Jekyllexclude不进入公开站点把工具链约定、风格底线、校验入口写死在上面。工具链统一走 Bundler把风格检查器mdl、vale、构建器jekyll、质量器html-proofer全部锁进 Gemfile配合HOMEBREW_NO_AUTO_UPDATE1类环境开关消除环境漂移。把风格规范翻译成可执行规则语义换行让 diff 干净表格对齐便于审阅而牛津逗号、术语大小写交给 Vale缩进交给 Markdownlint代码块交给 RuboCop——规范落在配置里才不会被遗忘。本地命令与 CI 命令一一对应rake lint、rake test、rake build分层封装CI 只做编排安装 Vale、缓存 proofer、上传产物逻辑全在本地可复现的 Rake 任务与配置文件里。特殊文件特殊处理Manpage.md、index.md使用独立 lint 规则见 docs/index.mdl_style.rb既保留首页的灵活性又不牺牲其余文档的严格度。结语docs/AGENTS.md篇幅虽短却精准浓缩了 Homebrew 文档工程化的全部要点面向docs/目录的明确边界、以brew bundle为锚的依赖管理、可被 Vale/Markdownlint/RuboCop 自动执行的行文规范以及一套与.github/workflows/docs.yml完全对齐的本地校验命令。对文档贡献者而言它是照做即通过 CI的捷径对正在搭建大型文档项目的团队而言它更是一份关于如何让文档质量检查从人工评审走向工程化流水线的成熟范本。【免费下载链接】brew The Package Manager for Everywhere项目地址: https://gitcode.com/GitHub_Trending/br/brew创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Homebrew 文档维护实战：docs/AGENTS.md 写作规范与校验工作流解析
Homebrew 文档维护实战docs/AGENTS.md 写作规范与校验工作流解析【免费下载链接】brew The Package Manager for Everywhere项目地址: https://gitcode.com/GitHub_Trending/br/brewdocs/AGENTS.md是 Homebrew/brew 仓库为文档贡献者无论人还是 AI Agent编写的操作说明它把 docs 站点维护的工具链选择、Markdown 写作风格和四层校验命令固定成一套可执行规范。本文围绕该文档展开结合 .github/workflows/docs.yml、docs/Rakefile、docs/Gemfile 与 Vale 风格库等仓库实况说明如何在本地复现与 Homebrew 官方一致的文档校验流水线。读完你将掌握一套从写作到 lint、到断链检查、再到 CI 发布的完整方法可以直接套用到任何 Jekyll 驱动的大型文档站点维护中。一、文档定位一份写给人与 AI Agent 的维护说明书docs/AGENTS.md带 Jekyll 前置元数据last_review_date: 2026-06-10标题为 Agent Instructions for Homebrew/brew docs开篇即限定适用范围These instructions apply when working indocs/。也就是说它是一份作用于目录边界的约定文档凡是在docs/目录下增删改文档都应遵守其规则。之所以需要这样一份说明是因为 Homebrew 的文档站点并非手写 HTML而是基于 Jekyll 静态站点工具链见 docs/_config.yml从几十篇 Markdown 生成 docs.brew.sh 等另有渠道。一个容易被忽略的细节是docs/_config.yml 的exclude列表中明确排除了AGENTS.md同时被排除的还有Gemfile*、Rakefile、vale-styles等工程性文件。这印证了 AGENTS.md 的定位它面向编辑者而不是读者不会被 Jekyll 构建成公开页面而是与仓库根目录的 AGENTS.md、CLAUDE.md 一脉相承作为人类协作者与 AI 编程助手共同的进场须知。从内容结构看这份文档由四部分组成下文逐一展开部分解决的问题Tooling用什么命令跑 docs 工具链、为什么不用./bin/brewMarkdown style文档写作的排版、拼写与链接规范Verification改完文档后本地要跑哪些校验Notes站点构建、Rake 任务与 manpage 再生成的补充约定二、工具链用brew bundle exec管理 docs 的 Ruby 环境AGENTS.md 的 Tooling 部分给出了三条关键约定直接决定了 docs 目录下所有命令的形态从docs/目录使用系统级 Homebrew 的brew bundle exec ...工作流而不是./bin/brew。原因在于 docs 站点是一个独立的 Ruby/Jekyll 项目依赖定义在 docs/Gemfile并不需要 brew 本体自举运行用brew bundle拉起的 Bundler 环境最贴近官方 CI.github/workflows/docs.yml 同样用bundle exec rake ...形式执行任务。所有校验命令都设置HOMEBREW_NO_AUTO_UPDATE1避免 brew 在跑校验时先触发自身自动更新从而与 CI 环境保持一致、加快反馈速度。这一点在 .github/workflows/docs.yml 的环境变量中同样成对出现另有HOMEBREW_DEVELOPER、HOMEBREW_NO_ENV_HINTS等。用brew bundle exec bundle install安装或刷新文档 Ruby 环境。docs/下存在 Brewfile 与 Gemfile前者描述 brew 侧需要的东西后者声明 Jekyll 及其插件。以 Ruby 侧为例docs/Gemfile 精确刻画了工具链的组成这也是我们理解后续每条校验命令的前提构建侧jekyll及插件组其中jekyll-relative-links负责把文档里的.md相对链接在渲染时解析为最终页面 URL这正是写链接只写文件名能成立的底层机制jekyll-seo-tag、jekyll-sitemap、jekyll-titles-from-headings等负责 SEO 元数据。文档侧yard与yard-sorbet对应 Rakefile 里从 Ruby 源码生成 YARD API 文档的任务。测试侧html-proofer断链与 HTML 合法性检查、mdlMarkdownlint、rake。典型的首次环境准备命令为# 在 docs/ 目录下执行 HOMEBREW_NO_AUTO_UPDATE1 brew bundle exec bundle install需要说明的是docs/下并没有现成的可执行文件bin/jekyll这类调用依赖 Bundler 对本地 binstub 或 gem 内可执行文件的解析brew bundle exec的职责就是保证解析发生在 Bundler 锁定的版本上。若你只是快速预览文档效果CI 中使用的等价路径是bundle exec rake build见 docs/Rakefile。三、写作规范文档风格的可机械化约束AGENTS.md 的 Markdown style 部分总结了 Homebrew 文档的排版底线每一句几乎都能在仓库的工具配置或样式指南里找到落点。下面是逐条解读与仓库佐证。3.1 语义换行与表格对齐每句话独占一行semantic line breaks而不是按固定列宽回行。这样 diff 只影响改动的句子review 时更干净。这条规范在 docs/Prose-Style-Guidelines.md 的 One sentence per source line in Markdown, without wrapping prose to a fixed width 中被再次确认。Markdown 表格要用空格补齐列宽让源文件里|竖线肉眼可对齐。虽然渲染结果一样但对协作审阅极其友好。3.2 拼写英式拼写与 licence / license 的语义分工全文使用英式拼写与标点。名词用licence动词用license但当指代确切接口名时保留原样license——例如 Formula DSL 中的license方法、命令行选项。仓库里 docs/Licence-Guidelines.md 一整篇都在讨论如何在现实语境下区分二者AGENTS.md 只是把结论收敛成一条可执行规则。3.3 标点与列表避免 em-dash破折号改用分号、冒号与逗号。不使用 Oxford comma牛津逗号。嵌套无序列表缩进 2 个空格。这两条均有工具背书。Vale 样式库 docs/vale-styles/Homebrew/OxfordComma.yml 会在正文中捕捉牛津逗号而 docs/index.mdl_style.rb 的rule MD007, indent: 2正是为无序列表缩进量身定制的 Markdownlint 配置。注意同文件中exclude_rule MD013关闭了行宽检查正是为了让每句一行的规范不被行宽规则误伤。3.4 链接与 URL禁止裸 URL一律使用 Markdown 链接。站内链接必须指向.md文件本身例如[Bottles](https://link.gitcode.com/i/20272004a445d48f7effe4666f2581a3)而不是docs.brew.sh的成品 URL。这背后的技术原因是jekyll-relative-links插件会在构建时把这些相对 Markdown 路径自动解析成站点内页面把链接写成.md还让仓库内浏览如 GitHub 代码视图也能直接跳转。按仓库根路径换算AGENTS.md 中示例Bottles.md实际指向 docs/Bottles.md。文档站点中这类相对链接在源文件里全部是文件名 .md的形式。四、校验工作流四类检查本地全量复现AGENTS.md 强调修改文档后应运行 .github/workflows/docs.yml 与 docs/Rakefile 中相关的检查。以下命令均以docs 目录为工作目录执行除明确注明仓库根的之外。4.1 环境与构建HOMEBREW_NO_AUTO_UPDATE1 brew bundle exec bundle install HOMEBREW_NO_AUTO_UPDATE1 brew bundle exec bin/jekyll build第一条确保依赖齐全第二条本地构建站点是后续 lint/test 的先决条件。docs/Rakefile 中rake build就是对bundle exec jekyll build的封装CI 正是通过bundle exec rake build.github/workflows/docs.yml执行的。4.2rake lintMarkdownlint 与元数据完整性HOMEBREW_NO_AUTO_UPDATE1 brew bundle exec bundle exec rake lintrake lintdocs/Rakefile实际做了两件事对git ls-files *.md追踪的文档跑mdl但排除Manpage.md与站点首页index.md首页单独使用 docs/index.mdl_style.rb 这份更宽松的规则它豁免了行宽、标题层级、裸 URL 等规则并把 MD007 缩进固定为 2。检查每个.md文件是否都带last_review_date前置元数据——这就是为什么 docs/AGENTS.md 自身顶部也有last_review_date: 2026-06-10。4.3rake testHTMLProofer 断链与结构检查HOMEBREW_NO_AUTO_UPDATE1 brew bundle exec bundle exec rake testrake testdocs/Rakefile会先构建站点再用html-proofer检查_site/产物重点包括4 线程并行、自定义 User-Agent兼容 403/429 反爬、校验 favicon 与 OpenGraph 标签、强制 HTTPS、并针对 GitHub 等外部 URL 配置一天缓存。因此它既能发现仓库内.md链接失效也能发现外部链接返回 404/403/429。在 CI 中该步骤只在 pull request 上执行并失败重跑一次.github/workflows/docs.yml因为每次全量外部检查成本较高。4.4 Vale 文案检查与 RuboCop 代码块风格AGENTS.md 明确要求在仓库根目录额外执行两条内容变更类检查rg --files docs -0 -g *.md -g !vendor/** -g !_site/** -g !rubydoc/** | xargs -0 vale HOMEBREW_NO_AUTO_UPDATE1 brew style docs第一条先把docs/下所有 Markdown排除构建产物与 vendor以 NUL 分隔喂给 Vale。Vale 的规则由 .vale.ini 指定样式路径为./docs/vale-styles同时适用于*.md与*.rb启用Homebrew样式集合。这一集合即 docs/vale-styles/Homebrew 下的多个 YAML 规则文件例如Terms.yml把Pull Request纠正为pull request、Rubocop纠正为RuboCop、非上下文的MacOS纠正为macOS、ruby纠正为Ruby。OxfordComma.yml拦截牛津逗号。另有 Headings.yml标题大小写、Spacing.yml空格等构成了一套可自动执行的风格约束层是人写规范 机器兜底的典型实践。第二条brew style docs用 RuboCop 检查文档中嵌入的 Ruby 代码块是否符合仓库的代码风格对应 CI 中的 Check code blocks conform to our Ruby style guide 步骤.github/workflows/docs.yml。4.5 manpage 与补全的联动再生成AGENTS.md 的 Notes 部分最后提醒当文档改动依赖 manpage 或补全脚本的更新时需要先运行brew generate-man-completions --no-exit-code在官方 CI 中这一步位于 Cleanup Homebrew/brew docs 步骤.github/workflows/docs.yml即对 Homebrew/brew 本体仓库在跑 Vale 之前先重新生成manpages/brew.1与 shell 补全--no-exit-code保证生成结果差异不阻断主流程。实现入口可参考 Library/Homebrew/cmd/generate-man-completions.rb。五、本地校验与 CI 的映射关系把 AGENTS.md 给出的本地命令与 .github/workflows/docs.yml 的 docs job 对照能清晰看到这套工作流的设计哲学让本地开发者/Agent 跑与 CI 完全一致的命令把提交后才被 CI 打回的概率降到最低。本地校验docs/ 下CI 对应步骤检查目标brew bundle exec bundle installSetup Rubybundler-cacheRuby 依赖就绪brew bundle exec rake lintCheck Markdown syntaxMarkdownlint last_review_datebrew style docsCheck code blocks…文档中 Ruby 代码块风格rake buildjekyll buildBuild the site站点可构建rake testCheck for broken links仅 PRHTMLProofer 断链检查rg ... \| xargs -0 valeInstall Vale vale docs/英式拼写、术语、逗号等文案brew generate-man-completionsCleanup Homebrew/brew docsmanpage 与补全同步此外针对 Homebrew/brew 本体CI 在全部检查通过后还会执行rake yard从Library/Homebrew的 Ruby 源码重新生成 YARD API 文档docs/Rakefile.github/workflows/docs.yml并最终把_site/作为 GitHub Pages 产物上传部署。部署失败时还会自动开/关 GitHub issue.github/workflows/docs.yml形成构建-检查-部署-告警的完整闭环。六、可复用的实践清单把 docs/AGENTS.md 的方法论抽象出来任何维护 Jekyll 类文档仓库的团队都可以照搬这套分工写一份只面向编辑者的 AGENTS 说明并确保它被 Jekyllexclude不进入公开站点把工具链约定、风格底线、校验入口写死在上面。工具链统一走 Bundler把风格检查器mdl、vale、构建器jekyll、质量器html-proofer全部锁进 Gemfile配合HOMEBREW_NO_AUTO_UPDATE1类环境开关消除环境漂移。把风格规范翻译成可执行规则语义换行让 diff 干净表格对齐便于审阅而牛津逗号、术语大小写交给 Vale缩进交给 Markdownlint代码块交给 RuboCop——规范落在配置里才不会被遗忘。本地命令与 CI 命令一一对应rake lint、rake test、rake build分层封装CI 只做编排安装 Vale、缓存 proofer、上传产物逻辑全在本地可复现的 Rake 任务与配置文件里。特殊文件特殊处理Manpage.md、index.md使用独立 lint 规则见 docs/index.mdl_style.rb既保留首页的灵活性又不牺牲其余文档的严格度。结语docs/AGENTS.md篇幅虽短却精准浓缩了 Homebrew 文档工程化的全部要点面向docs/目录的明确边界、以brew bundle为锚的依赖管理、可被 Vale/Markdownlint/RuboCop 自动执行的行文规范以及一套与.github/workflows/docs.yml完全对齐的本地校验命令。对文档贡献者而言它是照做即通过 CI的捷径对正在搭建大型文档项目的团队而言它更是一份关于如何让文档质量检查从人工评审走向工程化流水线的成熟范本。【免费下载链接】brew The Package Manager for Everywhere项目地址: https://gitcode.com/GitHub_Trending/br/brew创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考