repomix

Codex 兼容性说明：

• 在 Codex 中使用 $skill-name 调用仓库技能；此镜像副本会改写旧版 Claude /skill-name 引用。
• 任务跟踪要求：在执行任何工作流或技能步骤之前，先为所有步骤创建或更新任务跟踪，并随着进度变化保持同步。
• 用户提问提示表示要在 Codex 中直接询问用户。
• 忽略出现的 Claude 专属模式切换说明。
• 严格执行约定：用户明确调用某项技能时，按原样执行该技能协议。
• 子 Agent 授权：用户调用或 AI 检测到技能，且其协议要求使用子 Agent 时，该技能的激活即授权为该任务使用所需的 spawn_agent 子 Agent。
• 除非用户事先明确批准偏离，否则不得跳过、重排或合并协议步骤。
• 对于工作流技能，明确执行每个列出的子技能步骤，并逐步报告证据。
• 如果所需步骤或工具无法在此环境中运行，请停止并在调整方案前询问用户。

Codex 项目参考资料加载（无钩子）

Codex 不会通过 Claude 基于钩子的方式注入文档。 进行编码、规划、调试、测试或审查时，请按照此路由显式打开项目文档。

始终阅读：

• docs/project-config.json（项目专属路径、命令、模块以及工作流和测试设置）
• docs/project-reference/docs-index-reference.md（指向完整的 docs/project-reference/* 目录）
• docs/project-reference/lessons.md（始终适用的防护规则和反模式）

根据情况阅读的文档：

• 后端/CQRS/API/领域/实体变更：backend-patterns-reference.md、domain-entities-reference.md、project-structure-reference.md
• 前端/UI/样式/设计系统：frontend-patterns-reference.md、scss-styling-guide.md、design-system/README.md
• 规格/测试用例规划或 TC 映射：feature-docs-reference.md
• 集成测试实现/审查：integration-test-reference.md
• E2E 测试实现/审查：e2e-test-reference.md
• 代码审查/审计工作：根据变更文件阅读 code-review-rules.md 及上述领域文档

不要不加甄别地阅读所有文档。先从 docs-index-reference.md 开始，再仅打开与任务相关的文件。

快速摘要

目标： 使用 Repomix 将代码仓库打包成便于 AI 使用的单个文件，以供大模型分析。

工作流：

1. 评估 — 确定目标仓库（本地/远程）、输出格式和敏感性问题
2. 配置 — 设置包含/忽略模式、注释移除和输出样式
3. 执行 — 使用选项运行 repomix，监控令牌计数
4. 验证 — 检查输出中是否包含敏感数据，并确认令牌数量是否符合目标大模型的限制

关键规则：

• 分享前务必审查输出（检查 API 密钥、凭据等安全问题）
• 使用 --include 模式，将内容控制在大模型上下文限制内
• 默认输出格式为 XML；使用 --style markdown 可获得易读的输出
• 使用 --token-count-tree 在打包前找出令牌密集型文件

保持怀疑，运用批判性和顺序性思维。每项判断都必须有可追溯的证据和置信度百分比（想法的置信度应高于 80%）。

Repomix 技能

Repomix 可将整个仓库打包成便于 AI 使用的单个文件，非常适合将代码库提供给 Claude、ChatGPT 和 Gemini 等大模型。

适用场景

适用于：

• 打包代码库以供 AI 分析
• 为大模型上下文创建仓库快照
• 分析第三方库
• 为安全审计做准备
• 生成文档上下文
• 调查大型代码库中的错误
• 创建便于 AI 使用的代码表示

快速开始

检查安装情况

repomix --version

安装

# npm
npm install -g repomix

# Homebrew (macOS/Linux)
brew install repomix

基本用法

# Package current directory (generates repomix-output.xml)
repomix

# Specify output format
repomix --style markdown
repomix --style json

# Package remote repository
npx repomix --remote owner/repo

# Custom output with filters
repomix --include "src/**/*.ts" --remove-comments -o output.md

核心功能

仓库打包

• 采用针对 AI 优化的格式，分隔清晰
• 支持多种输出格式：XML、Markdown、JSON、纯文本
• 感知 Git 的处理方式（遵循 .gitignore）
• 统计 Token 数量，便于管理大模型上下文
• 检查敏感信息

远程仓库支持

无需克隆即可处理远程仓库：

# Shorthand
npx repomix --remote yamadashy/repomix

# Full URL
npx repomix --remote https://github.com/owner/repo

# Specific commit
npx repomix --remote https://github.com/owner/repo/commit/hash

移除注释

从支持的语言中移除注释（HTML、CSS、JavaScript、TypeScript、Vue、Svelte、Python、PHP、Ruby、C、C#、Java、Go、Rust、Swift、Kotlin、Dart、Shell、YAML）：

repomix --remove-comments

常见用例

代码审查准备

# Package feature branch for AI review
repomix --include "src/**/*.ts" --remove-comments -o review.md --style markdown

安全审计

# Package third-party library
npx repomix --remote vendor/library --style xml -o audit.xml

生成文档

# Package with docs and code
repomix --include "src/**,docs/**,*.md" --style markdown -o context.md

调查 Bug

# Package specific modules
repomix --include "src/auth/**,src/api/**" -o debug-context.xml

实施规划

# Full codebase context
repomix --remove-comments --copy

命令行参考

文件选择

# Include specific patterns
repomix --include "src/**/*.ts,*.md"

# Ignore additional patterns
repomix -i "tests/**,*.test.js"

# Disable .gitignore rules
repomix --no-gitignore

输出选项

# Output format
repomix --style markdown  # or xml, json, plain

# Output file path
repomix -o output.md

# Remove comments
repomix --remove-comments

# Copy to clipboard
repomix --copy

配置

# Use custom config file
repomix -c custom-config.json

# Initialize new config
repomix --init  # creates repomix.config.json

Token 管理

Repomix 会自动统计各个文件、整个仓库以及每种输出格式的 Token 数量。

大模型的典型上下文限制：

• Claude Sonnet 4.5：约 200K 个 Token
• GPT-4：约 128K 个 Token
• GPT-3.5：约 16K 个 Token

优化 Token 数量

了解代码库中 Token 的分布，对于优化 AI 交互至关重要。使用 --token-count-tree 选项可直观查看项目中的 Token 用量：

repomix --token-count-tree

此命令会显示代码库的层级视图以及 Token 数量：

🔢 Token Count Tree:
────────────────────
└── src/ (70,925 tokens)
    ├── cli/ (12,714 tokens)
    │   ├── actions/ (7,546 tokens)
    │   └── reporters/ (990 tokens)
    └── core/ (41,600 tokens)
        ├── file/ (10,098 tokens)
        └── output/ (5,808 tokens)

还可以设置最低 Token 阈值，以聚焦较大的文件：

repomix --token-count-tree 1000  # Only show files/directories with 1000+ tokens

这有助于：

• 找出 Token 占用较高、可能超出 AI 上下文限制的文件
• 使用 --include 和 --ignore 模式优化文件选择
• 针对占用最大的文件制定压缩策略
• 为 AI 分析准备代码时，平衡内容与上下文

安全注意事项

Repomix 使用 Secretlint 检测敏感数据（API 密钥、密码、凭据、私钥、AWS 密钥）。

最佳实践：

1. 分享前务必检查输出
2. 使用 .repomixignore 排除敏感文件
3. 处理未知代码库时启用安全检查
4. 将 .env 文件排除在打包内容之外
5. 检查是否存在硬编码的凭据

如有需要，可禁用安全检查：

repomix --no-security-check

实施工作流

当用户请求打包仓库时：

1. 评估需求

   • 确定目标仓库（本地或远程）
   • 确定所需的输出格式
   • 检查敏感数据相关问题

2. 配置筛选条件

   • 为相关文件设置包含模式
   • 为不需要的文件添加忽略模式
   • 启用或禁用注释移除功能

3. 执行打包

   • 使用适当的选项运行 repomix
   • 监控 Token 数量
   • 验证安全检查结果

4. 验证输出

   • 检查生成的文件
   • 确认不含敏感数据
   • 检查是否符合目标大模型的 Token 限制

5. 交付上下文

   • 向用户提供打包后的文件
   • 附上 Token 数量摘要
   • 说明任何警告或问题

参考文档

如需详细信息，请参阅：

• 配置参考 - 配置文件、包含／排除模式、输出格式、高级选项
• 用法模式 - AI 分析工作流、安全审计准备、文档生成、库评估

其他资源

• GitHub：https://github.com/yamadashy/repomix
• 文档：https://repomix.com/guide/
• MCP 服务：可用于与 AI 助手集成

---

[IMPORTANT] 开始前使用任务跟踪，将所有工作拆分为小任务——包括每个文件读取任务。这可避免长文件导致上下文丢失。对于简单任务，AI 必须注意询问用户是否跳过。

防止 AI 出错——每项任务都要避免以下失败模式： 删除前检查下游引用。 删除组件会导致文档和代码出现连锁过时问题。移除前先梳理所有引用该组件的文件。 根据实际代码核实 AI 生成的内容。 AI 会臆造 API、类名和方法签名。记录或引用前，务必使用 grep 确认其存在。 编辑后追踪完整依赖链。 修改定义时，可能会遗漏下游变量及其消费者。务必追踪完整链路。 核实正确性时追踪所有代码路径。 确认代码存在不代表确认它会执行。务必追踪提前退出、错误分支和条件跳过，而不只是正常路径。 调试时，修复前先问“这是谁的职责？”。 追踪问题是在调用方（数据错误）还是被调用方（处理错误）。在负责的层级修复，绝不要只修补症状出现的位置。 假设现有值是有意设置的——修改前先问为什么。 修改任何常量、限制、标志或模式前：阅读注释、检查 git blame，并查看周边代码。 核实所有受影响的输出，而不只是第一个。 涉及多个技术栈的更改，必须核实每个输出。一个检查通过，不代表所有检查都通过。 整体优先的调试方式——避免只关注最近的问题。 调查任何故障时，先列出所有前置条件（配置、环境变量、数据库名称、端点、DI 注册、数据前置条件），再逐一对照证据核实，然后再提出任何代码层面的假设。 精准修改——执行差异检查。 修复 Bug：每一处更改都必须能直接追溯到该 Bug。不要顺手重整格式或改进相邻代码。增强任务：实现改进并明确说明。 编码前指出歧义，不要默默选择。 如果请求存在多种解释，列出每种解释、估算所需工作量并询问。绝不要擅自假设要处理所有记录、采用基于文件的方案或更复杂的路径。

批判性思维模式——运用批判性思维和顺序思维。每项结论都必须有可追溯的证据，置信度 >80% 才能采取行动。 防止幻觉： 绝不要把猜测当作事实；每项结论都要引用来源，坦然承认不确定性，自查输出是否有误，独立交叉核验，并对自己的判断保持怀疑——缺乏证据的确信是一切幻觉的根源。

必须注意运用批判性思维——每项结论都必须有可追溯的证据，置信度 >80% 才能采取行动。防止幻觉：绝不要把猜测当作事实。

必须注意落实 AI 防错措施——整体优先调试、在负责的层级修复、编码前指出歧义，并在压缩后重新阅读文件。

收尾提醒

重要，必须注意：开始前使用任务跟踪，将工作拆分为小型待办任务 重要，必须注意：创建新代码前，在代码库中搜索 3+ 个相似模式 重要，必须注意：每项结论都要引用 file:line 证据（置信度 >80% 才能采取行动） 重要，必须注意：添加最终审核待办任务，检查工作质量

[TASK-PLANNING] 行动前，分析任务范围，并使用任务跟踪系统地将其拆分为小型待办任务和子任务。

无钩子提示词协议镜像（自动同步）

来源：.claude/hooks/lib/prompt-injections.cjs + .claude/.ck.json

[WORKFLOW-EXECUTION-PROTOCOL] [BLOCKING] 工作流执行协议 — 强制、重要、必须、关键。无论出于何种原因，都不得跳过。

通用可移植性边界： 可复用的技能和协议文本应与项目无关；从 docs/project-config.json 和 docs/project-reference/ 中查找项目特定约定。应用 shared/sdd-artifact-contract.md 中的共享 AI-SDD。阅读 docs/project-config.json 和 docs/project-reference/docs-index-reference.md，然后打开其中列出的项目参考文档。只要具备此共享上下文和本地文档，任何受支持的 AI 工具都可以执行。

1. 检测： 将提示词与工作流目录进行匹配
2. 分析： 找出最匹配的工作流，并评估自定义步骤组合是否更合适
3. 询问（必需格式）： 直接向用户提问，采用以下结构；除非用户明确调用了某个工作流／技能，且本地协议将明确调用视为确认：
   • 问题："你想启用哪个工作流？"
   • 选项 1："启用 [最佳匹配工作流]（推荐）"
   • 选项 2："启用自定义工作流：[步骤 1 → 步骤 2 → ...]"（附上一句话说明理由）
4. 启用（确认后）： 标准工作流调用 $workflow-start <workflowId>；自定义步骤按顺序手动执行
5. 创建任务： 跟踪工作流的所有步骤
6. 执行： 按顺序遵循每个步骤 [CRITICAL-THINKING-MINDSET] 运用批判性思维和顺序思维。每项声明都必须有可追溯的证据；置信度超过 80% 才能采取行动。 反幻觉原则： 切勿将猜测当作事实；每项声明都要引用来源；坦率承认不确定性；自行检查输出是否有误；独立交叉核对；对自己的判断保持怀疑——没有证据的确信是所有幻觉的根源。 AI 注意力原则（首因－近因效应）： 对于较长的提示词／协议，将最关键的 3 条规则同时放在开头和结尾，以确保指令在较长上下文窗口中仍能得到遵循。 目标驱动执行： 先定义成功标准，循环执行直至验证通过，并且只有在可观察的检查均通过后才停止。 测试验证意图： 测试必须保护业务规则／不变量，并在受保护的意图被破坏时失败，而不能只照搬当前行为。

[LESSON-LEARNED-REMINDER] [BLOCKING] 任务规划与持续改进 — 强制执行。不得跳过。

开始前将工作拆分为小任务并进行跟踪。添加最终任务："分析 AI 错误与经验教训"。

提取经验教训——仅限根本原因，不处理表面症状：

1. 指明失败模式（推理／假设失误），而非症状——例如“未阅读源代码就假设 API 存在”，而不是“使用了错误的枚举值”。
2. 通用性测试：此失败模式是否适用于 ≥3 种情境／代码库？如果不适用，就再抽象一层。
3. 将其写成通用规则——去除项目特定的名称／路径／类。该规则应适用于任何代码库。
4. 合并：多个错误若有相同的失败模式 → 总结为一条经验教训。
5. 重复发生检查：“如果没有这条提醒，未来会话中还会发生这种情况吗？”——不会 → 跳过 $learn。
6. 自动修复检查：“$code-review／$code-simplifier／$security／$lint 能否发现此问题？”——能 → 改进相应的审查技能。
7. 两项检查均通过 → 请用户运行 $learn。 [TASK-PLANNING] [MANDATORY] 在执行任何工作流或技能步骤之前，先为所有计划步骤创建／更新任务跟踪；然后随着每个步骤开始／完成，持续同步任务状态。