Codebase Flattener Tool  程式碼庫平整工具

The BMAD-METHOD™ includes a powerful codebase flattener tool designed to prepare your project files for AI model consumption when uploading to web AI tools. This tool aggregates your entire codebase into a single XML file, making it easy to share your project context with AI assistants for analysis, debugging, or development assistance.
BMAD-METHOD™ 包含一個強大的程式碼庫平整工具，專為在上傳至網路 AI 工具時準備專案檔案以供 AI 模型使用而設計。此工具會將整個程式碼庫彙整成單一的 XML 檔案，方便與 AI 助手分享專案上下文以進行分析、除錯或開發協助。

Features  功能

• AI-Optimized Output: Generates clean XML format specifically designed for AI model consumption
  AI 最佳化輸出：產生專為 AI 模型使用而設計的乾淨 XML 格式
• Smart Filtering: Automatically respects .gitignore patterns to exclude unnecessary files, plus optional project-level .bmad-flattenignore for additional exclusions if planning to flatten an existing repository for external update and analysis
  智慧過濾：自動遵循 .gitignore 模式以排除不必要的檔案，並可選擇使用專案層級的 .bmad-flattenignore 以進一步排除（適用於計劃將現有版本庫攤平成以供外部更新與分析時）
• Binary File Detection: Intelligently identifies and excludes binary files, focusing on source code
  二進位檔案偵測：智慧識別並排除二進位檔案，專注於原始程式碼
• Progress Tracking: Real-time progress indicators and comprehensive completion statistics
  進度追蹤：即時進度指示與完整的完成統計
• Flexible Output: Customizable output file location and naming
  彈性輸出：可自訂輸出檔案的位置與命名

Usage  使用說明

# Basic usage - creates flattened-codebase.xml in current directory
npx bmad-method flatten

# Specify custom input directory
npx bmad-method flatten --input /path/to/source/directory
npx bmad-method flatten -i /path/to/source/directory

# Specify custom output file
npx bmad-method flatten --output my-project.xml
npx bmad-method flatten -o /path/to/output/codebase.xml

# Combine input and output options
npx bmad-method flatten --input /path/to/source --output /path/to/output/codebase.xml

Example Output  範例輸出

The tool will display progress and provide a comprehensive summary:
該工具會顯示進度並提供完整摘要：

📊 Completion Summary:
✅ Successfully processed 156 files into flattened-codebase.xml
📁 Output file: /path/to/your/project/flattened-codebase.xml
📏 Total source size: 2.3 MB
📄 Generated XML size: 2.1 MB
📝 Total lines of code: 15,847
🔢 Estimated tokens: 542,891
📊 File breakdown: 142 text, 14 binary, 0 errors

The generated XML file contains your project's text-based source files in a structured format that AI models can easily parse and understand, making it perfect for code reviews, architecture discussions, or getting AI assistance with your BMAD-METHOD™ projects.
產生的 XML 檔案以結構化格式包含您專案的文字型原始檔，便於 AI 模型解析與理解，非常適合用於程式碼審查、架構討論或尋求 AI 對您 BMAD-METHOD™ 專案的協助。

Advanced Usage & Options  進階用法與選項

• CLI options   CLI 選項
  • -i, --input <path>: Directory to flatten. Default: current working directory or auto-detected project root when run interactively.
    -i, --input <path> ：要攤平的目錄。預設：目前工作目錄，或在互動式執行時自動偵測的專案根目錄。
  • -o, --output <path>: Output file path. Default: flattened-codebase.xml in the chosen directory.
    -o, --output <path> ：輸出檔案路徑。預設：所選目錄中的 flattened-codebase.xml 。
• Interactive mode   互動模式
  • If you do not pass --input and --output and the terminal is interactive (TTY), the tool will attempt to detect your project root (by looking for markers like .git, package.json, etc.) and prompt you to confirm or override the paths.
    如果你沒有傳入 --input 與 --output ，且終端為互動式（TTY），該工具會嘗試偵測你的專案根目錄（透過尋找像 .git 、 package.json 等標記），並提示你確認或覆寫這些路徑。
  • In non-interactive contexts (e.g., CI), it will prefer the detected root silently; otherwise it falls back to the current directory and default filename.
    在非互動情境（例如 CI）中，工具會靜默地採用偵測到的根目錄；否則會回退到目前目錄與預設檔名。
• File discovery and ignoring
  檔案發現與忽略
  • Uses git ls-files when inside a git repository for speed and correctness; otherwise falls back to a glob-based scan.
    在位於 git 儲存庫內時使用 git ls-files 以提高速度和正確性；否則回退為基於 glob 的掃描。
  • Applies your .gitignore plus a curated set of default ignore patterns (e.g., node_modules, build outputs, caches, logs, IDE folders, lockfiles, large media/binaries, .env*, and previously generated XML outputs).
    套用你的 .gitignore 加上一組精選的預設忽略模式（例如 node_modules 、建置輸出、快取、日誌、IDE 資料夾、鎖定檔案、大型媒體/二進位檔、 .env* ，以及先前產生的 XML 輸出）。
  • Supports an optional .bmad-flattenignore file at the project root for additional ignore patterns (gitignore-style). If present, its rules are applied after .gitignore and the defaults.
    支援在專案根目錄放置可選的 .bmad-flattenignore 檔案以加入額外的忽略模式（gitignore 風格）。如果存在，其規則會在 .gitignore 與預設項目之後套用。

.bmad-flattenignore example   .bmad-flattenignore 範例

Create a .bmad-flattenignore file in the root of your project to exclude files that must remain in git but should not be included in the flattened XML:
在專案根目錄建立一個 .bmad-flattenignore 檔案，用以排除那些必須保留在 git 中但不應包含在展平後 XML 的檔案：

seeds/**
scripts/private/**
**/*.snap

• Binary handling   二進位處理
  • Binary files are detected and excluded from the XML content. They are counted in the final summary but not embedded in the output.
    二進位檔案會被偵測並從 XML 內容中排除。它們會在最終摘要中計數，但不會嵌入輸出中。
• XML format and safety
  XML 格式與安全性
  • UTF-8 encoded file with root element <files>.
    以 UTF-8 編碼的檔案，根元素為 <files> 。
  • Each text file is emitted as a <file path="relative/path"> element whose content is wrapped in <![CDATA[ ... ]]>.
    每個文字檔案都作為一個 <file path="relative/path"> 元素輸出，其內容被包裹在 <![CDATA[ ... ]]> 中。
  • The tool safely handles occurrences of ]]> inside content by splitting the CDATA to preserve correctness.
    該工具會透過拆分 CDATA 來處理內容中出現的 ]]> ，以確保正確性。
  • File contents are preserved as-is and indented for readability inside the XML.
    檔案內容以原樣保留並為了在 XML 內的可讀性而縮排。
• Performance   效能
  • Concurrency is selected automatically based on your CPU and workload size. No configuration required.
    會根據您的 CPU 與工作負載大小自動選擇並行度，無需任何設定。
  • Running inside a git repo improves discovery performance.
    在 git 倉庫內執行可提升偵測效能。

Minimal XML example  最簡單的 XML 範例

<?xml version="1.0" encoding="UTF-8"?>
<files>
<file path="src/index.js"><![CDATA[
// your source content
]]></file>
</files>