Repomix 项目 AI 协作开发指南：从仓库布局到编码规范与提交约定的完整实践

Repomix 项目 AI 协作开发指南：从仓库布局到编码规范与提交约定的完整实践

【免费下载链接】repomix📦 Repomix is a powerful tool that packs your entire repository into a single, AI-friendly file. Perfect for when you need to feed your codebase to Large Language Models (LLMs) or other AI tools like Claude, ChatGPT, DeepSeek, Perplexity, Gemini, Gemma, Llama, Grok, and more.项目地址: https://gitcode.com/GitHub_Trending/rep/repomix

Repomix 是一款将整个仓库内容打包为单一 AI 友好文件（支持 XML、Markdown、JSON、Plain Text）的工具，其核心目标是把代码库投喂给 Claude、ChatGPT、DeepSeek 等 LLM 使用。本文以仓库根目录的CLAUDE.md为骨架，结合src/、tests/、website/、browser/的真实实现与配置文件，系统梳理参与 Repomix 开发时需要遵循的仓库布局、编码规范、非显然陷阱、提交信息约定、依赖注入与测试方式，以及输出生成原则，帮助你快速理解项目约束并写出符合规范的代码。

一、项目定位与文档入口

CLAUDE.md开篇即定义了 Repomix 的核心定位：

A tool that packs repository contents into a single AI-friendly file. Supports XML, Markdown, JSON, and plain text output formats.

这与 README.md 中"pack your entire repository into a single, AI-friendly file"的描述一致。该文件被设计为alwaysApply的 AI 协作准则（frontmatter 中alwaysApply: true），意味着任何 AI 工具在参与本仓库代码、文档或配置的修改时都应自动套用其中规则。

CLAUDE.md本身非常精简，仅提供导航与核心约束，完整项目概览请参阅 README.md，贡献流程请参阅 CONTRIBUTING.md。其中，CLAUDE.md 提到的"完整项目概览"在 README 中对应了快速开始、CLI 用法、远程仓库处理、输出格式、MCP 集成等完整章节，可作为理解项目能力的总入口。

二、仓库布局：功能化目录与"镜像"测试结构

CLAUDE.md明确给出了四大部分：

• src/— 主源码，按功能划分（cli/、config/、core/、shared/），功能之间避免相互依赖；
• tests/— 与src/目录结构一一镜像；
• website/— 文档站点（VitePress），文档存放在website/client/src/下 15 个语言目录（en+ 14 个翻译 locale）；
• browser/— 浏览器扩展。

从仓库实际结构验证，这一约定确实被严格执行：src/下每一层功能模块（core/file/、core/git/、core/metrics/、core/output/、core/security/、core/skill/、core/tokenCount/、core/treeSitter/）在tests/中都有同名目录对应；tests/core/file/fileCollect.test.ts对应src/core/file/fileCollect.ts，tests/cli/cliRun.test.ts对应src/cli/cliRun.ts。这种"镜像结构"让开发者定位某个功能的测试文件零成本。

"功能之间避免依赖"的约束，从源码上也能观察到印证：各 feature 目录下的模块大多通过shared/目录（logger.ts、patternUtils.ts、processConcurrency.ts 等）共享基础能力，而不是跨 feature 直接引用。

说明：CLAUDE.md中仓库布局未提到的根级文件（如repomix.config.json、biome.json、vitest.config.ts）同样属于工程基础设施，下文会在对应章节涉及。

三、编码规范：Biome 统一风格与单文件职责

3.1 Biome 强制约束

项目使用 biome.json 作为唯一代码风格裁判，CLAUDE.md要求遵循其强制规范。从配置可以确认具体规则：

• 格式化：缩进为 2 空格，行宽 120 字符（indentStyle: space、indentWidth: 2、lineWidth: 120）；
• JavaScript 格式：单引号、尾随逗号全量（trailing comma）、分号必填；
• Linter：启用 recommended 规则集，.vue文件关闭未使用变量/导入检查（Vue 模板中很常见）；
• JSON 解析：允许注释与尾随逗号（allowComments、allowTrailingCommas），这正是 repomix.config.json 中能出现// ignore is specified in .repomixignore这类注释的原因。

另外，src/index.ts被单独 override 关闭了 import 自动整理（organizeImports: off），说明入口文件的导入顺序有手工维护的特殊性。

3.2 单文件职责：约 250 行是"信号"而非"硬限制"

CLAUDE.md对单文件长度给出了极具可操作性的指导：

Treat ~250 lines as a signal to review a file's cohesion, not a mandate to split.

即：当文件接近 250 行时提示审视内聚性，而不是机械拆分。若长度来源于单一内聚关注点（如大型数据/配置表），应保持原样；只有当文件混入了多种职责时才拆分。仓库中 defaultIgnore.ts 就是很好的正面例子——它包含上百条内置忽略模式（VCS、依赖目录、日志、缓存、构建产物、各语言锁文件等），但全部服务于"默认忽略清单"这一个职责，因此无需拆分。

3.3 注释与测试要求

• 非显然逻辑处必须添加英文注释（"Add comments in English where non-obvious logic exists"）；
• 新功能必须提供对应的单元测试。

这一要求在源码中有大量落实，例如 fileProcess.ts 用注释明确交代了轻量转换的执行顺序及其原因："removeEmptyLinesruns afterremoveCommentsso that empty lines created by comment removal are cleaned up."，而 tests/core/file/fileProcess.test.ts 则配套验证了该管线行为。

3.4 验证命令

CLAUDE.md要求修改后运行两条命令：

npm run lint # Ensure code style compliance npm run test # Verify all tests pass

从 package.json 可见，npm run lint实际上串联了四个子任务：lint-biome（biome check --write）、lint-oxlint（oxlint --fix）、lint-ts（tsc --noEmit 类型检查）、lint-secretlint（密钥扫描），而npm run test即vitest。

四、非显然规则与陷阱（重点章节）

CLAUDE.md专门列出了五条"容易踩坑"的规则，这是参与开发前必须熟记的核心约束：

4.1 配置 JSON Schema 禁止手改

website/client/src/public/schemas/下的 JSON Schema 是自动生成的，通过npm run website-generate-schema生成，且 CI 会在合并到main后重新生成。因此永远不要手工编辑这些文件。生成脚本位于 website/client/scripts/generateSchema.ts，底层由 configSchema.ts 中基于 valibot 定义的 schema 通过@valibot/to-json-schema转换而来。

这也解释了为什么repomix.config.json顶部有"$schema": "https://repomix.com/schemas/latest/schema.json"—— 该 URL 指向的正是这份自动生成的 schema，保证编辑器能对配置文件做实时校验。

4.2 面向用户的功能变更必须更新全部 15 种语言文档

任何用户可见的选项或功能变更，文档都要同步更新到website/client/src/下全部 15 个语言目录，而不是只改en。这一约束直接保证了多语言文档的一致性。仓库中website/client/src/下确实存在en、de、es、fr、hi、id、it、ja、ko、pt-br、ru、tr、vi、zh-cn、zh-tw共 15 个目录，且每个目录下的guide/均保持相同的文件结构（如usage.md、configuration.md、mcp-server.md等）。

4.3 根目录 lint 不检查网站客户端

根目录的npm run lint不会对website/client做类型检查。改动website/client时，必须在该目录下单独运行npm run docs:build验证。这一点从 package.json 的lint-ts只执行根级tsc --noEmit即可确认——website 客户端有自己独立的 tsconfig.json 与 package.json。

4.4 重命名标题需检索锚点链接

VitePress 构建不会校验页内锚点链接。因此重命名某个标题后，必须全局搜索指向旧锚点的文档链接并同步更新，否则会出现"静默失效"的死链。

4.5 GitHub Actions 必须固定完整 commit SHA

所有 GitHub Actions step 必须固定到完整的 commit SHA，并附带版本注释，例如：

uses: actions/checkout@<sha> # v7.0.0

CI 中由pinact和zizmor两个工具强制检查这一点，防止供应链攻击（tag 可被篡改，而 commit SHA 不可变）。

五、提交信息与 PR 规范

5.1 Conventional Commits

提交信息遵循 Conventional Commits 规范，带 scope，格式为type(scope): Description，例如：

feat(cli): Add new --no-progress flag

• scope：受影响区域（cli、core、website、security等）；
• Description：现在时、以大写字母开头、清晰简洁；
• commit body：遵循contextual-commitskill（位于.claude/skills/contextual-commit/SKILL.md）。

在仓库实际提交历史中，这一风格贯穿始终，例如 cliRun.ts 中--token-budget、--sandbox、--skill-generate等选项的演进都遵循feat(cli): ...模式。

5.2 PR 指南

• 遵循.github/pull_request_template.md模板；
• 顶部包含清晰的变更摘要；
• 用#issue-number引用相关问题；
• 同一区域的小而相关的改动合并进一个 PR，而不是拆散。

六、依赖注入与测试：deps对象模式

这是CLAUDE.md中技术含量最高的一节，也是 Repomix 代码库最具特色的工程实践。核心要求是：

Inject dependencies through adepsobject parameter for testability.

即每个函数通过末尾的deps参数注入依赖，而不是直接调用全局函数：

export const functionName = async ( param1: Type1, param2: Type2, deps = { defaultFunction1, defaultFunction2, } ) => { // Use deps.defaultFunction1() instead of direct call };

配套规则：通过deps对象传入测试替身（test doubles）来 mock 依赖；仅当依赖注入不可行时才使用vi.mock()。

从源码中可以找到大量典型实践：

• fileProcess.ts 的processFiles注入{ initTaskRunner, getFileManipulator }；
• securityCheck.ts 的runSecurityCheck注入{ initTaskRunner, getProcessConcurrency }；
• cliRun.ts 的canonicalizeSandboxRoot注入{ realpath, stat }（这正是便于在测试中模拟fs.realpath抛错、fs.stat返回目录等边界场景的关键设计）。

对应测试如 tests/core/file/fileProcess.test.ts、tests/core/security/securityCheck.test.ts 均通过向deps传入 stub 来隔离真实 IO。

这种模式的优点很明显：函数无需任何 mock 框架即可在纯内存中测试，且默认参数保证了生产环境零配置即可运行。deps默认值的写法（直接引用导入的函数）也保证了类型安全。

七、输出生成原则

CLAUDE.md最后一条规定了输出生成的底线：

• 除非另行指定，所有内容必须完整包含，不得缩写（"Include all content without abbreviation, unless specified otherwise"）；
• 面向大型代码库优化，同时保持输出质量。

这一原则在输出管线中得到贯彻：例如 outputGenerate.ts 负责将全部文件内容组装进最终产物，配合--split-output拆分输出（outputSplit.ts）与--compress压缩（src/core/treeSitter）等机制，在"内容不缩写"与"控制体积"之间取得平衡——压缩是通过 Tree-sitter 提取类/函数签名等结构化信息来实现的，而非简单截断内容。

八、结合配置与源码的实战补充

虽然CLAUDE.md本身不包含配置文件示例，但其"保持面向用户功能一致性"的原则直接体现在仓库根级 repomix.config.json 中——它本身就是 Repomix 自举使用的真实配置，可作为学习配置结构的范本：

• input.maxFileSize：单个文件大小上限（50000000 字节，即 50MB，与 configSchema.ts 的默认值一致）；
• output.style/filePath：输出格式与路径；
• output.git：git 相关选项（按变更排序、包含 diff/log 等）；
• ignore：useGitignore、useDefaultPatterns、customPatterns三段式忽略控制；
• security.enableSecurityCheck：是否启用 Secretlint 密钥扫描；
• tokenCount.encoding：token 计数编码（默认o200k_base）。

其中 ignore 的完整语义对应 defaultIgnore.ts 中数百条内置模式与.gitignore、.ignore、.repomixignore的叠加；安全扫描对应 securityCheck.ts 中基于 worker 线程批量执行的实现（批次 50 个文件，最多 2 个 worker 以减少与指标计算的资源竞争）。

总结

CLAUDE.md虽短，却是理解 Repomix 工程文化的钥匙：功能化目录 + 镜像测试结构保证了可维护性；Biome 统一风格 + 250 行内聚信号保证了代码一致性；deps依赖注入模式让测试摆脱 mock 框架；15 语言文档同步、schema 自动生成、Actions SHA 固定等"非显然规则"则筑起了质量与安全的护城河。对于任何计划为 Repomix 贡献代码或扩展其能力的开发者，先吃透这份准则，再对照 CONTRIBUTING.md 走完流程，就能以最低摩擦融入项目协作。

【免费下载链接】repomix📦 Repomix is a powerful tool that packs your entire repository into a single, AI-friendly file. Perfect for when you need to feed your codebase to Large Language Models (LLMs) or other AI tools like Claude, ChatGPT, DeepSeek, Perplexity, Gemini, Gemma, Llama, Grok, and more.项目地址: https://gitcode.com/GitHub_Trending/rep/repomix