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/repomixRepomix 是一款将整个仓库内容打包为单一 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 个翻译 localebrowser/— 浏览器扩展。从仓库实际结构验证这一约定确实被严格执行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.tstests/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: 120JavaScript 格式单引号、尾随逗号全量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 files 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-biomebiome check --write、lint-oxlintoxlint --fix、lint-tstsc --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/checkoutsha # v7.0.0CI 中由pinact和zizmor两个工具强制检查这一点防止供应链攻击tag 可被篡改而 commit SHA 不可变。五、提交信息与 PR 规范5.1 Conventional Commits提交信息遵循 Conventional Commits 规范带 scope格式为type(scope): Description例如feat(cli): Add new --no-progress flagscope受影响区域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.gitgit 相关选项按变更排序、包含 diff/log 等ignoreuseGitignore、useDefaultPatterns、customPatterns三段式忽略控制security.enableSecurityCheck是否启用 Secretlint 密钥扫描tokenCount.encodingtoken 计数编码默认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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
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/repomixRepomix 是一款将整个仓库内容打包为单一 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 个翻译 localebrowser/— 浏览器扩展。从仓库实际结构验证这一约定确实被严格执行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.tstests/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: 120JavaScript 格式单引号、尾随逗号全量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 files 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-biomebiome check --write、lint-oxlintoxlint --fix、lint-tstsc --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/checkoutsha # v7.0.0CI 中由pinact和zizmor两个工具强制检查这一点防止供应链攻击tag 可被篡改而 commit SHA 不可变。五、提交信息与 PR 规范5.1 Conventional Commits提交信息遵循 Conventional Commits 规范带 scope格式为type(scope): Description例如feat(cli): Add new --no-progress flagscope受影响区域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.gitgit 相关选项按变更排序、包含 diff/log 等ignoreuseGitignore、useDefaultPatterns、customPatterns三段式忽略控制security.enableSecurityCheck是否启用 Secretlint 密钥扫描tokenCount.encodingtoken 计数编码默认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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考