Repomix 自定义指令Custom Instructions完全指南为 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 允许你在打包输出中注入自定义指令Custom Instructions让 Claude、ChatGPT、DeepSeek 等 AI 系统在处理仓库时获得项目专属的背景信息、编码规范、架构上下文与审查目标。本指南基于官方文档与仓库源码完整讲解output.instructionFilePath配置项的使用方法、输出格式、底层实现原理与实战建议读完即可为自己的仓库配置一套可复用的 AI 分析指令。自定义指令能解决什么问题Repomix 的核心能力是把整个仓库打包成单一文件交给 AI 处理。但模型在分析代码时往往缺少这个项目的背景是什么、应该重点关注哪些目录、遵循什么编码规范这类上下文导致分析结果泛泛而谈。自定义指令机制就是为此设计的你可以在打包输出文件中附带一段 Markdown 指令相当于在交给 AI 的试卷里附上答题须知例如声明项目的技术栈与架构组织方式帮助 AI 快速定位核心模块标注需要重点审查的安全检查点、性能敏感路径明确输出要求如回答时引用文件路径、忽略测试目录等传递团队的编码规范与代码评审目标。指令内容会以独立的 Instruction 部分出现在输出文件中位于仓库结构、文件内容之前确保 AI 系统在处理代码前先读到这些约束。快速开始三步接入自定义指令第一步创建指令文件在仓库根目录创建一个 Markdown 文件例如repomix-instruction.md文件名可自定义本仓库根目录就存在一个真实的 repomix-instruction.md 可供参考# 仓库指令 本仓库包含 Repomix 工具的源代码。分析代码时请遵循以下指南 1. 重点关注 src/core 目录中的核心功能。 2. 特别留意 src/core/security 中的安全检查。 3. 忽略 tests 目录中的所有文件。第二步在配置文件中声明路径在repomix.config.json的output对象下设置instructionFilePath指向指令文件相对于项目根目录的路径{ output: { instructionFilePath: repomix-instruction.md } }第三步运行并查看输出执行打包命令如repomix或npx repomix后指令内容会自动被读取并注入输出文件。无需其他额外操作。完整示例与各格式下的输出效果沿用上面的指令文件在默认的 XML 输出格式style: xml默认输出文件repomix-output.xml下生成结果会包含如下独立部分instruction # 仓库指令 本仓库包含 Repomix 工具的源代码。分析代码时请遵循以下指南 1. 重点关注 src/core 目录中的核心功能。 2. 特别留意 src/core/security 中的安全检查。 3. 忽略 tests 目录中的所有文件。 /instruction从源码结构看指令渲染并不局限于 XML 格式。三个输出样式模板都预留了指令插槽仅在配置了instructionFilePath时才输出该部分xmlStyle.ts以instruction标签包裹markdownStyle.ts以## Instruction小节标题呈现plainStyle.ts以Instruction文本标题呈现。三种格式均使用{{#if instruction}}条件判断 {{{instruction}}}原样插值保证指令内容包括其中的 Markdown 语法不被转义破坏。底层原理从配置到输出的完整链路理解实现链路有助于排查问题与发挥该功能的全部能力。1. 配置 Schema 校验instructionFilePath在输出配置 schema 中被声明为可选的字符串字段分别出现在基础 schema 与默认 schema 中configSchema.ts基础 schemainstructionFilePath: v.optional(v.string())configSchema.ts默认 schema无默认值未配置即为空它与headerText自定义文件头文本、style输出格式等同属output配置对象可由repomix.config.json或 CLI 参数提供。2. 读取与注入buildOutputGeneratorContext核心实现位于输出上下文构建函数中outputGenerate.tslet repositoryInstruction ; if (config.output.instructionFilePath) { const instructionPath path.resolve(config.cwd, config.output.instructionFilePath); try { repositoryInstruction await fs.readFile(instructionPath, utf-8); } catch { throw new RepomixError(Instruction file not found at ${instructionPath}); } }关键细节路径以config.cwd为基准通过path.resolve解析因此配置中的路径应相对于运行 Repomix 的工作目录通常是仓库根目录文件以 UTF-8 编码整体读取不经过任何过滤或大小限制处理读取成功后指令内容被放入输出生成上下文outputGenerate.ts 的instruction: repositoryInstruction随后由各样式模板渲染若文件不存在会抛出明确的RepomixError错误Instruction file not found at 绝对路径而非静默忽略。3. CLI 参数方式除配置文件外指令路径也可以通过命令行直接指定cliRun.tsrepomix --instruction-file-path repomix-instruction.md对应的 CLI 选项类型声明见 cli/types.ts。使用命令行参数时无需修改配置文件适合临时或脚本化场景。4. 行为验证测试用例仓库测试对核心行为有明确覆盖outputGenerate.test.ts配置instructionFilePath: INSTRUCTIONS.md后上下文中的instruction字段等于文件内容验证读取并注入链路当指令文件缺失模拟 ENOENT时构建过程抛出RepomixError且错误信息匹配/Instruction file not found/验证错误处理分支。CLI 侧测试cliRun.test.ts则验证了--instruction-file-path path/to/instruction.txt参数能正确透传到配置对象。编写高质量指令的实战建议指令的质量直接决定 AI 分析的准确度。参考本仓库真实使用的 repomix-instruction.md一个优秀的指令文件通常包含以下层次一句话项目定位说明仓库是什么、为谁服务例如Repomix 是一个将软件仓库内容打包成单一文件以便 AI 系统分析的工 具结构导航用目录树或要点列出核心目录及其职责例如src/core/file/负责文件处理、src/core/security/负责敏感信息安全检查帮助 AI 建立代码地图明确的分析优先级指明重点与忽略项例如忽略tests目录关注安全检查实现约束与要求如注释必须使用英文、依赖通过 deps 对象注入、新功能需配套单元测试等让 AI 的产出符合团队规范可验证的收尾动作例如运行npm run lint与npm run test验证改动。此外建议指令内容保持精炼——它会被原样写入输出文件并占用 token 额度重点放在模型难以从代码本身推断出的信息背景、目标、规范而非重复代码中已有的内容。注意事项与限制未配置时零开销不设置instructionFilePath时repositoryInstruction为空字符串所有样式模板通过{{#if instruction}}跳过指令部分输出中不会出现空指令小节路径基准是 cwd配置值相对于config.cwd解析跨目录运行时如从子目录执行需使用正确相对路径或绝对路径文件缺失会中断打包与可选配置的宽松态度不同指令文件若无法读取会直接抛出RepomixError终止流程这是刻意设计——保证每次输出都携带完整上下文沙箱安全上下文从源码注释看cli/types.ts 附近的skipGlobalConfig说明在不可信 Agent 上下文--sandbox下会跳过全局配置因为配置驱动的output.instructionFilePath存在读取工作区外文件并泄露到输出中的风险实际使用时应避免在指令文件中放置敏感信息。相关资源Configuration 指南output配置对象的完整字段说明输出格式指南XML、Markdown、Plain、JSON 等格式差异Prompt 示例面向 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Repomix 自定义指令（Custom Instructions）完全指南：为 AI 打包输出注入项目级上下文
Repomix 自定义指令Custom Instructions完全指南为 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 允许你在打包输出中注入自定义指令Custom Instructions让 Claude、ChatGPT、DeepSeek 等 AI 系统在处理仓库时获得项目专属的背景信息、编码规范、架构上下文与审查目标。本指南基于官方文档与仓库源码完整讲解output.instructionFilePath配置项的使用方法、输出格式、底层实现原理与实战建议读完即可为自己的仓库配置一套可复用的 AI 分析指令。自定义指令能解决什么问题Repomix 的核心能力是把整个仓库打包成单一文件交给 AI 处理。但模型在分析代码时往往缺少这个项目的背景是什么、应该重点关注哪些目录、遵循什么编码规范这类上下文导致分析结果泛泛而谈。自定义指令机制就是为此设计的你可以在打包输出文件中附带一段 Markdown 指令相当于在交给 AI 的试卷里附上答题须知例如声明项目的技术栈与架构组织方式帮助 AI 快速定位核心模块标注需要重点审查的安全检查点、性能敏感路径明确输出要求如回答时引用文件路径、忽略测试目录等传递团队的编码规范与代码评审目标。指令内容会以独立的 Instruction 部分出现在输出文件中位于仓库结构、文件内容之前确保 AI 系统在处理代码前先读到这些约束。快速开始三步接入自定义指令第一步创建指令文件在仓库根目录创建一个 Markdown 文件例如repomix-instruction.md文件名可自定义本仓库根目录就存在一个真实的 repomix-instruction.md 可供参考# 仓库指令 本仓库包含 Repomix 工具的源代码。分析代码时请遵循以下指南 1. 重点关注 src/core 目录中的核心功能。 2. 特别留意 src/core/security 中的安全检查。 3. 忽略 tests 目录中的所有文件。第二步在配置文件中声明路径在repomix.config.json的output对象下设置instructionFilePath指向指令文件相对于项目根目录的路径{ output: { instructionFilePath: repomix-instruction.md } }第三步运行并查看输出执行打包命令如repomix或npx repomix后指令内容会自动被读取并注入输出文件。无需其他额外操作。完整示例与各格式下的输出效果沿用上面的指令文件在默认的 XML 输出格式style: xml默认输出文件repomix-output.xml下生成结果会包含如下独立部分instruction # 仓库指令 本仓库包含 Repomix 工具的源代码。分析代码时请遵循以下指南 1. 重点关注 src/core 目录中的核心功能。 2. 特别留意 src/core/security 中的安全检查。 3. 忽略 tests 目录中的所有文件。 /instruction从源码结构看指令渲染并不局限于 XML 格式。三个输出样式模板都预留了指令插槽仅在配置了instructionFilePath时才输出该部分xmlStyle.ts以instruction标签包裹markdownStyle.ts以## Instruction小节标题呈现plainStyle.ts以Instruction文本标题呈现。三种格式均使用{{#if instruction}}条件判断 {{{instruction}}}原样插值保证指令内容包括其中的 Markdown 语法不被转义破坏。底层原理从配置到输出的完整链路理解实现链路有助于排查问题与发挥该功能的全部能力。1. 配置 Schema 校验instructionFilePath在输出配置 schema 中被声明为可选的字符串字段分别出现在基础 schema 与默认 schema 中configSchema.ts基础 schemainstructionFilePath: v.optional(v.string())configSchema.ts默认 schema无默认值未配置即为空它与headerText自定义文件头文本、style输出格式等同属output配置对象可由repomix.config.json或 CLI 参数提供。2. 读取与注入buildOutputGeneratorContext核心实现位于输出上下文构建函数中outputGenerate.tslet repositoryInstruction ; if (config.output.instructionFilePath) { const instructionPath path.resolve(config.cwd, config.output.instructionFilePath); try { repositoryInstruction await fs.readFile(instructionPath, utf-8); } catch { throw new RepomixError(Instruction file not found at ${instructionPath}); } }关键细节路径以config.cwd为基准通过path.resolve解析因此配置中的路径应相对于运行 Repomix 的工作目录通常是仓库根目录文件以 UTF-8 编码整体读取不经过任何过滤或大小限制处理读取成功后指令内容被放入输出生成上下文outputGenerate.ts 的instruction: repositoryInstruction随后由各样式模板渲染若文件不存在会抛出明确的RepomixError错误Instruction file not found at 绝对路径而非静默忽略。3. CLI 参数方式除配置文件外指令路径也可以通过命令行直接指定cliRun.tsrepomix --instruction-file-path repomix-instruction.md对应的 CLI 选项类型声明见 cli/types.ts。使用命令行参数时无需修改配置文件适合临时或脚本化场景。4. 行为验证测试用例仓库测试对核心行为有明确覆盖outputGenerate.test.ts配置instructionFilePath: INSTRUCTIONS.md后上下文中的instruction字段等于文件内容验证读取并注入链路当指令文件缺失模拟 ENOENT时构建过程抛出RepomixError且错误信息匹配/Instruction file not found/验证错误处理分支。CLI 侧测试cliRun.test.ts则验证了--instruction-file-path path/to/instruction.txt参数能正确透传到配置对象。编写高质量指令的实战建议指令的质量直接决定 AI 分析的准确度。参考本仓库真实使用的 repomix-instruction.md一个优秀的指令文件通常包含以下层次一句话项目定位说明仓库是什么、为谁服务例如Repomix 是一个将软件仓库内容打包成单一文件以便 AI 系统分析的工 具结构导航用目录树或要点列出核心目录及其职责例如src/core/file/负责文件处理、src/core/security/负责敏感信息安全检查帮助 AI 建立代码地图明确的分析优先级指明重点与忽略项例如忽略tests目录关注安全检查实现约束与要求如注释必须使用英文、依赖通过 deps 对象注入、新功能需配套单元测试等让 AI 的产出符合团队规范可验证的收尾动作例如运行npm run lint与npm run test验证改动。此外建议指令内容保持精炼——它会被原样写入输出文件并占用 token 额度重点放在模型难以从代码本身推断出的信息背景、目标、规范而非重复代码中已有的内容。注意事项与限制未配置时零开销不设置instructionFilePath时repositoryInstruction为空字符串所有样式模板通过{{#if instruction}}跳过指令部分输出中不会出现空指令小节路径基准是 cwd配置值相对于config.cwd解析跨目录运行时如从子目录执行需使用正确相对路径或绝对路径文件缺失会中断打包与可选配置的宽松态度不同指令文件若无法读取会直接抛出RepomixError终止流程这是刻意设计——保证每次输出都携带完整上下文沙箱安全上下文从源码注释看cli/types.ts 附近的skipGlobalConfig说明在不可信 Agent 上下文--sandbox下会跳过全局配置因为配置驱动的output.instructionFilePath存在读取工作区外文件并泄露到输出中的风险实际使用时应避免在指令文件中放置敏感信息。相关资源Configuration 指南output配置对象的完整字段说明输出格式指南XML、Markdown、Plain、JSON 等格式差异Prompt 示例面向 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考