fixmap

音声付きの31秒の FixMap ワークフロー動画を見る

ホームページのサンプルでタスクを試してみてください。バンドルされた sample-api プロジェクトを使い、タブ内で実際の FixMap Plan エンジンが動作します。リポジトリを確認したり、タスクのテキストをアップロードしたりすることはありません。自分のリポジトリで使うにははじめにを、より高度なワークフローを試すにはフルブラウザデモを開いてください。

インストール

Node.js 20.11 以降が必要です。

npm install --global @aryam/fixmap@latest
fixmap plan --issue https://github.com/chalk/chalk/issues/624

一度だけ試す場合：

npx -y @aryam/fixmap@latest plan --issue https://github.com/chalk/chalk/issues/624

Claude Code、Cursor、GitHub Copilot、Agent Skills で呼び出せる /fixmap コマンドをインストールします：

fixmap setup

機能メニュー全体を見るには、タスクを指定せずに /fixmap と入力するか、ターミナルで fixmap features を実行してください。連携機能を1つインストールするには fixmap setup --agent <name> を使い、既存のカスタマイズ済みコマンドを確認したうえで必要な場合にのみ --force を指定してください。

FixMap は公開タスクを取得し、そのリポジトリを推定して、一時的に隔離されたチェックアウトをスキャンし、レポートが完成したら削除します。ローカルリポジトリの分析でソースがアップロードされることはありません。

日常のワークフロー

編集前にプランを保存します。

fixmap plan --issue "password reset emails fail" --format json --output plan.json

このプランでは、主要なコンテキストと影響の可能性が高い対象を分けています。対象には、インポート、逆方向の依存先、ルーティングされたテスト、繰り返し発生する Git の共変更関係が含まれます。影響対象ファイルは確認する場所であり、編集が必要だと決めつけるものではありません。

ご自身のリポジトリの履歴で BM25、FixMap、Impact Graph を測定します。

fixmap benchmark --repo . --last 50

エージェントが編集する間、保存したプランをそばに置いておきます。Watch は作業ツリーが変更された場合にのみ新しい検証結果を出力し、実際の差分をもとに影響を再計算します。

fixmap watch --report plan.json --repo . --include-untracked

ファイル名だけでなく、関連するソース範囲をエージェントに渡します。Context は主要ファイルと影響対象ファイルから情報を集め、推定ソーストークン数の予算内に収めます。

fixmap context --issue "password reset emails fail" --budget 10000

プルリクエスト、Issue、設計メモ向けに、エビデンスグラフをエクスポートします。

fixmap graph --issue "password reset emails fail" --format mermaid

エージェントのコンテキストウィンドウでは、簡潔な見出しを使用します。

fixmap plan --issue "password reset emails fail" --format agent

想定したパスが見つからない理由を尋ねます。

fixmap plan --issue "password reset emails fail" --explain src/auth/token.ts

タスクを調整し、ランキングを比較します。

fixmap plan --issue "sendMail throws during password reset" --compare plan.json

保存したプランに照らして、完了した差分を検証します。

fixmap verify --report plan.json --diff main...HEAD

別のツールに渡す前に、保存したレポートを検証します。

fixmap validate plan.json

ステージ済みおよび未ステージの追跡対象の編集には --working-tree を、新しいファイルを変更として扱うには --include-untracked を、マップの対象を絞るには --exclude または .fixmapignore を使用します。また、強制的に新しくスキャンするには --no-cache を使用します。警告相当の指摘で CI を失敗させる必要がある場合は、Verify に --fail-on warning を追加します。すべてのコマンドを確認するには fixmap --help を実行してください。

機能一覧

入力とリポジトリのマッピング

• 公開 GitHub Issue またはプルリクエストの URL、プレーンなタスクテキスト、UTF-8 または UTF-16 の --issue-file（BOM のない一般的な Windows UTF-16 ファイルを含む）、または stdin からのタスクテキストを受け付けます。
• www、クエリ文字列、フラグメントを含む、対応ブラウザーおよび GitHub API の Issue URL を正規化します。一方で、認証情報、類似ホスト、ポート、安全でないエンコード済みパスは拒否します。
• 現在のチェックアウト、別のローカルパス、file:// URL、または公開 GitHub リポジトリの分離されたチェックアウトをスキャンします。
• --diff <spec>、--base／--head、または現在の --working-tree をマッピングします。追跡されていない変更は、--include-untracked を指定した場合にのみ含まれます。
• リポジトリのルート、コミット、ステータス、バイナリ差分がすべて同一の場合にのみ、リポジトリの生スキャンを再利用します。タスクテキスト、--limit、除外ルールはスキャン後に適用されるため、これらを変更しても同じキャッシュ済みファイルを安全に再利用しつつ、新たにランキングしてフィルタリングしたレポートを生成できます。Compare は現在のプランをスキャンし、Verify は渡されたレポートを、新規または完全に同じ状態のリポジトリマップに照らして検証します。cache-hit は再利用とスキャンからの経過時間を報告し、エントリーは 7 日後に期限切れになります。OS のキャッシュの保存先は FIXMAP_CACHE_DIR で変更できます。CLI の --no-cache、MCP の noCache: true、または Action の no-cache: true を指定すると、新しいスキャンを強制できます。
• 現在の --issue-file、--compare、--report、--output の各成果物は、リポジトリのランキング、変更検出、キャッシュの無効化から除外されるため、FixMap が自身のレポートを修正箇所として推奨することはありません。
• npm、pnpm、Yarn、Bun のプロジェクトを検出し、各ワークスペースパッケージで宣言されたスクリプトを読み取ります。ルートに宣言がない場合は、一致するネストされたロックファイルから推測できます。一方、ルートの宣言が競合する場合は、暗黙に一方を選ぶのではなく、診断を出します。

計画とランキング

• パスの用語、ソースの内容、識別子、引用された断片（スマートクォートやギュメを含む）、ファイルへの言及、実際の差分の内容から、ソース、テスト、設定、ドキュメント、その他のファイルをランク付けします。
• JavaScript／TypeScript の宣言テスト、Go の _test.go、Python の test_*.py と *_test.py、一般的なテストディレクトリ、フレームワークの単一ファイルコンポーネントを認識します。
• 管理されているソースが存在する場合、ロックファイル、同期クライアントのバックアップ、バンドル済みの出力、サンプル、生成された対応ファイルの優先度を下げます。一方、deep-copy.ts や追跡対象のファーストパーティー vendor/ ソースなどの通常のモジュールは、引き続きランク付けの対象とします。
• 実際のパッケージスクリプトから実行可能なテストコマンドを特定し、最も関連性の高いテストファイルと組み合わせます。対象として特定した JavaScript、Python、Go、Rust のテストがスキップ、無視、条件付き、またはゲート付きの場合は警告します。
• 認証、課金、自動化、データ、パブリック API、依存関係という、6 つの範囲を限定したリスク領域を報告します。
• タスクの根拠、ランキングの構成、未解決または部分的に一致した識別子、除外項目、スキャンの制限、未読の内容、スキップされたサブモジュール、空の差分、Git の失敗について説明します。
• 厳密な小数値の --limit、繰り返し指定可能な --exclude、否定パターンに対応した順序付きの .fixmapignore パターンをサポートします。ルート起点のパターンはリポジトリ相対として扱われ、リポジトリ内の貼り付けられた絶対パスは正規化されます。一致するものがないパターンには警告が表示されます。上限によって変わるのは表示される行数のみで、信頼度やランキングの構成分析は変わりません。

Impact Graph とリポジトリのベンチマーク

• 直接のインポート、逆方向の依存先、特定したテスト、主要なランク付け対象ファイルと繰り返し一緒に変更された Git ファイルから、影響を受ける可能性が高いファイルを別のビューとして構築します。
• マージコミットを除く最大 1,000 件のコミットを読み取り、30 ファイルを超える変更を含むコミットを除外します。共起が少なくとも 2 回必要です。また、根拠を捏造するのではなく、履歴が浅い場合や利用できない場合はその旨を示します。
• Verify 中に実際に変更されたファイルを中心に影響範囲を再計算し、当初の計画に含まれていない、根拠の強い依存先を必須の編集箇所ではなく、確認用の注記として示します。
• fixmap benchmark --repo . --last 50 は、過去の親スナップショットを使って BM25-over-code、通常の FixMap コンテキスト、Impact Graph を評価します。各ケースの履歴は対象の変更より前で止まり、すべての方式が同じスキャン済みコーパスを参照します。生成された対応ファイルは主要な回答として採点されず、言及されたタスクとされていないタスクは別々に報告されます。
• fixmap watch --report plan.json --repo . はローカルの作業ツリーを監視し、Verify を再実行し、編集が変更された場合にのみ影響範囲を再計算します。リポジトリのコードは実行しません。--format json は、更新ごとに 1 つの JSON オブジェクトを出力します。
• ベンチマークの Markdown とバージョン管理された JSON には、Wilson 区間、除外されたケースの数、二次ファイルの再現率、安全策、ケースごとの生の結果が含まれます。過去のコミットメッセージを使った結果は、リポジトリ固有のバックテストであり、エージェントによる工数削減の証明ではありません。

コンテキストパックとグラフのエクスポート

• fixmap context は、主要ファイルと影響ファイルから決定的な行範囲を選択し、各スニペットを「主要」または「影響」としてラベル付けします。また、その理由、信頼度、行範囲、推定トークンコスト、ソースの切り詰め、ファイルを除外した理由を記録します。
• 予算では、ソースのサイズを安定した推定値 ceil(UTF-8 bytes / 4) でカウントします。メタデータは対象外です。これは再現可能な計画用の推定値であり、特定のトークナイザーに対する正確なカウントではありません。
• コンテキストでは、大きなファイル全体ではなく、FixMap の上限付きスキャナーサンプルを使う場合があります。sourceTruncated により、その境界を JSON と Markdown で明示します。
• fixmap graph は、同じ Impact Graph を Mermaid またはバージョン管理された JSON としてエクスポートし、インポート、インポート元、テスト経路、同時変更の方向と根拠を保持します。

除外パターンの構文

--exclude と .fixmapignore では、リポジトリ相対の gitignore 形式のパターンを使用します。/docs/** はリポジトリのルートを基準にし、docs/** は同じルートディレクトリとその下の階層にあるディレクトリに一致します。!docs/keep.md は、それ以前に除外されたパスを再び含め、末尾の / はディレクトリを対象とします。*、?、** を使用できます。{src,test} のような波括弧で囲まれたグループは、選択肢ではなく文字列として扱われます。リテラル名に含まれるカンマを曖昧さなく扱うには、--exclude フラグを繰り返し指定するか、.fixmapignore の各行にパターンを1つずつ記述してください。

• 人間向けの Markdown、ツール向けのバージョン管理された JSON、または簡潔な EDIT CANDIDATE／INSPECT／TEST／RISK／AVOID／UNCERTAINTY セクションを出力する --format agent を生成します。--output を指定すると、任意の形式で書き出せます。

Explain、Compare、Verify、Validate、Doctor

• Explain は、パスがランク付けされたか、しきい値を下回ったか、除外されたか、サブモジュール経由で解決されたか、スキャンされなかったかを示します。また、Plan と同じタスクおよび差分のエビデンスを使用します。
• Compare は、タスクを絞り込んだ後に追加、削除、移動されたファイルや、確信度が変化したファイルに加え、タスクの根拠付けの変化も表示します。
• Verify は、保存済みの JSON プランと差分または作業ツリーを比較し、影響を再計算します。また、生成された編集、マッピングされていない変更、未変更の先頭ファイル、テストを伴わないソース変更、新たに到達したリスク領域、プランとリポジトリの不一致にフラグを立てます。既定ではエラーがあると失敗します。--fail-on warning と Action の fail-on: warning を指定すると、注意事項もオプトインの CI ゲートとして扱われます。
• Validate は、Compare、Verify、Action、MCP で共有される構造互換性バリデーターを使って、保存済みの JSON レポートを検証します。
• Doctor は、実行中のバージョンと実行ファイルのパスを表示し、プロジェクト、グローバル、PATH、npm-exec の各バージョンによる競合を診断します。
• FIXMAP_PROGRESS はリモートのクローン／スキャンの進行状況を制御し、FIXMAP_VERBOSE_USAGE は引数エラーの後に詳細な使用方法を再表示します。

エージェントと自動化のインターフェース

• fixmap setup は、Claude Code、Cursor、GitHub Copilot のプロンプトファイル、オープン Agent Skills レイアウト向けに /fixmap の検出設定をインストールします。引数なしで実行すると、変更を行う前に FixMap のすべてのワークフローを一覧表示します。
• MCP サーバーは、ローカルの stdio 経由で fixmap_plan、fixmap_context、fixmap_graph、fixmap_explain、fixmap_compare、fixmap_verify、fixmap_doctor を公開しており、公式 MCP Registry に掲載されています。
• GitHub Action は、プルリクエストで Plan または Verify を実行し、ジョブサマリーの残りの 1 MiB の予算内で追記します。レポート出力とコメントには上限を設け、コメントが重複して投稿されないよう、FixMap のコメントを1つ作成または更新します。
• Action は明示的なタスク入力またはプルリクエストのコンテキストを受け付け、CLI および MCP サーバーと同じレポートバリデーターを使用します。また、要求された差分を解決できない場合は、明確なエラーを返します。
• ホームページのタスクマッパーは、同梱の sample-api リポジトリに対して実際の Plan ロジックを実行し、フォールバック結果を捏造せずにエンジンの不確実性状態を保持します。
• 完全なブラウザデモは、タスクをアップロードせずに、同じサンプルリポジトリに対して実際のコア Plan、Explain、Compare、Verify ロジックを実行します。

TypeScript ライブラリ

• @aryam/fixmap-core は、リポジトリのスキャン、除外の解決、ランキング、Context Pack と Impact Graph の構築、BM25 による検索、タスクの根拠付け、言語／インポート解析、テスト／リスクのルーティング、レポートの検証、Markdown／JSON／agent／Mermaid 形式へのレンダリングを公開します。
• 公開 API では Explain、Compare、Verify のビルダーと結果型も公開するため、別のツールから CLI を呼び出すことなく、同じワークフローを組み合わせて利用できます。
• @aryam/fixmap-core/browser エントリでは、ファイルシステムに依存しないレポート、比較、説明、検証、レンダリングのロジックをブラウザバンドルで実行します。

信頼性、互換性、エビデンス

• コアは決定論的でローカル優先です。アカウント、API キー、ホスト型モデル、ソースのアップロード、依存関係のインストール、リポジトリのスクリプト、テストの実行、Git フックは必要ありません。
• 公開リポジトリの分析では、一時的な浅いチェックアウトを使用し、認証情報、継承された Git 設定、フック、LFS のスムージング、シンボリックリンク、サブモジュールの走査を無効にします。
• reportVersion: 1 が JSON の互換性境界を定義します。フィールドの追加は許可され、バージョンマーカーのない従来のレポートも引き続き受け入れられます。未対応のバージョンには、対処方法を示すメッセージが表示されます。
• チェックイン済みの自己評価、外部評価、ホールドアウト、敵対的テスト、パフォーマンス記録がエビデンスページに活用されます。CI では、空のコホート、信頼度ゲート、生成アセットの差分、Action バンドルの差分、1,000 ファイルのベンチマークをチェックします。
• ドキュメントサイトには、ライブデモ、インストール方法、見逃しを含むエビデンス、リリース変更履歴、レスポンシブナビゲーション、キーボードフォーカス、AA コントラスト、システム設定に対応するライト／ダークテーマが継続的に適用されます。

レポートの内容

• スコア、信頼度、エビデンスを含む、順位付けされたコンテキストファイル。
• 関係性ごとのエビデンス、信頼度、履歴の網羅状況、確認順を含む、影響を受ける可能性の高いファイル。
• リポジトリで実際に宣言されているコマンドに対応するテストルート。
• 認証、請求、自動化、データ、パブリック API、依存関係の 6 つの範囲に限定されたリスク領域。
• 不確実性、未読の内容、スキャン境界、除外された一致、未解決の差分に関する診断。
• 管理対象のソースが存在する場合に、生成された対応ファイルを避ける、根拠に基づいた次のアクション。

FixMap は決定論的です。調査範囲を絞り込みますが、順位付けや変更の正しさを証明するものではありません。

MCP サーバー

ローカル stdio 経由で Plan、Context、Graph、Explain、Compare、Verify、Doctor を公開します：

fixmap mcp

クライアント設定の例：

{
  "mcpServers": {
    "fixmap": {
      "command": "fixmap",
      "args": ["mcp"]
    }
  }
}

クライアントごとの手順については、MCP セットアップガイドをご覧ください。

GitHub Action

name: FixMap
on: pull_request

permissions:
  contents: read
  issues: write
  pull-requests: write

jobs:
  fixmap:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
      - uses: aryamthecodebreaker/[email protected]
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

Action はジョブのサマリーに範囲を限定したレポートを書き込み、プルリクエストのコメントを 1 件維持します。GitHub の制限によりレポートを切り詰める必要がある場合、通知に完全なレポートを保存するためのローカルの --output とアーティファクトのアップロード方法が示されます。ワークフローで正確な状態のスキャンキャッシュを回避するには no-cache: true を、Verify の参考情報がジョブの失敗条件となるようにするには fail-on: warning を設定します。チェックイン済みのバンドルとメタデータは、リリースのゲート対象です。

JSON 互換性

新しいプランには "reportVersion": 1 が含まれます。レポートのバージョン内ではフィールドを追加できますが、既存のフィールドを削除したり、型を変更したりすることはありません。利用側は不明なフィールドを無視してください。出力に対する破壊的変更には、新しいレポートバージョンが必要です。Compare と Verify は、引き続きマーカーのない従来のプランを受け入れ、未対応のマーカー値を拒否します。

エビデンス

エビデンスページは、チェックイン済みのホールドアウト、回帰、ベースライン、パフォーマンス、敵対的テストの記録から生成されます。ヒットと併せて、見逃しと信頼区間も公開します。CI では、空の評価ファイル、古くなったレンダリング済みアセット、敵対的テストの回帰、Action バンドルの差分、ベンチマークの差分を拒否します。

安全性の境界

FixMap は読み取りと順位付けを行います。依存関係のインストール、リポジトリのスクリプトの実行、テストの実行、Git フックの呼び出し、ローカルソースのアップロード、ホスト型モデルの呼び出しは行いません。リモートクローンでは、認証情報ヘルパー、継承された Git 設定、フック、サブモジュール、シンボリックリンク、LFS のスムージングを無効にします。

信頼モデルと報告手順については、SECURITY.mdをご覧ください。

ローカルでの開発

npm ci
npm run ci

ワークスペースには、決定論的なコア、CLI/MCP サーバー、GitHub Action、Next.js ウェブサイト、ベンチマーク、例、リリーススクリプトが含まれています。CONTRIBUTING.mdから始めてください。アーキテクチャと使用方法の詳細は、ドキュメントサイトをご覧ください。

リリース

リリースノートはCHANGELOG.mdと、生成されたウェブサイトの変更履歴に掲載されています。公開ワークフローでは、内部バージョン、npm パッケージ、MCP Registry のメタデータ、Action のメタデータとバンドル、GitHub リリース、およびインストール済み CLI が正常な状態であることを検証してから、リリースが完了します。

ライセンス

MIT