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/repomix

Repomix 允许你在打包输出中注入自定义指令（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（基础 schema）：instructionFilePath: v.optional(v.string())
configSchema.ts（默认 schema）：无默认值，未配置即为空

它与headerText（自定义文件头文本）、style（输出格式）等同属output配置对象，可由repomix.config.json或 CLI 参数提供。

2. 读取与注入：buildOutputGeneratorContext

核心实现位于输出上下文构建函数中（outputGenerate.ts）：

let 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.ts）：

repomix --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存在读取工作区外文件并泄露到输出中的风险；实际使用时应避免在指令文件中放置敏感信息。

企业官网建设流程全解析