KITAQ DEVELOPMENT SYSTEM
USER'S MANUAL 2026.09

KITAQ SERIES • REFERENCE EDITION

SARAKURA

診断・比較・再テスト

初めての一行から、実行・観測・再テストまで。
ローカルソース採取：2026年9月14日

1　SARAKURAの仕事

SARAKURAは、コンパイラのビルド情報とエミュレータの診断イベントを整理し、修正や再テストを考えやすい形へ変換します。ROMを実行するエミュレータでも、Cコードを勝手に修正するプログラムでもありません。

2　準備

powershell
Push-Location .\sarakura
.\scripts\build.ps1
.\sarakura.exe --help
Pop-Location

以下の sarakura はPATHが通った場合の略記です。通常は作成したEXEへのパスに置き換えて実行します。GBは gb analyze、FCは fc analyze を選びます。

3　初めての診断

必要な入力は2種類です。--metadata はビルド時のJSON、--events は実行時に出した診断JSONLです。JSONLは1行に1個のJSONオブジェクトが入る形式です。

powershell
sarakura gb analyze --metadata .\out\build.json --events .\out\gb_events.jsonl --out .\out\report --fail-on error

出力の report.html をブラウザーで開きます。最初に対象、観測フレーム、エラー件数、警告件数を確認し、それから個々の診断を読みます。--frames は解析条件の情報で、SARAKURAがその数だけROMを実行する指定ではありません。

4　入力を先に点検する

powershell
sarakura inspect-metadata --metadata .\out\build.json
sarakura inspect-events --events .\out\gb_events.jsonl
sarakura emitter-check gb --metadata .\out\build.json --events .\out\gb_events.jsonl --strict

ファイルが読めない、platformが違う、event_typeが規約と合わない、といった問題を先に分けます。通常のエミュレータJSONレポートをeventsに渡すだけでは、正しい診断入力になりません。

5　診断の読み方

errorは優先して調べる問題、warnは条件次第で問題になり得る観測、infoは参考情報です。分類は重大さの手掛かりで、ゲームの意図を完全には理解しません。例えばタイトルの待機ループとゲームのフリーズは、CPUが同じ場所を回るという観測だけでは区別できない場合があります。

ROMのSHA、入力手順、場面、画面、音、ソース位置を一緒に確認します。修正する前後で条件を揃えないと、診断が減った理由がコード改善なのか別場面を走ったからなのかわからなくなります。

6　出力ファイルの役割

標準の説明文・診断ヒント・修正指示は英語です。HTMLには lang="en" を指定しています。利用者が渡した文字列やイベントIDを自動翻訳するものではありません。通常は一部のプロジェクト名・パスを置換しますが、アドレスや観測内容をすべて匿名化する機能ではありません。解析結果を公開する際は内容を確認してください。

ファイル読み方
ai_diagnostics.json機械が扱いやすい正規化診断
diagnostic_summary.json件数と概要
report.html人が読むHTML報告
repair_prompt.md修正検討を始めるための説明
repair_plan.json / .md修正順や対象の計画
automation_plan.json / .mdツール能力を踏まえた作業計画
retest_plan.json再確認の計画
repro_bundle.zip再現情報の束

計画が作られたことと、その計画が実行されたことは別です。CファイルやROMを修正したら、コンパイラ→エミュレータ→SARAKURAをもう一度実行します。

7　カタログ・絞り込み・カバレッジ

powershell
sarakura catalog gb --json
sarakura catalog fc --json
sarakura pack-plan gb
sarakura coverage gb --events .\out\gb_events.jsonl --out .\out\coverage.json

catalogは診断ルールの一覧、pack-planは分野ごとの組、coverageは今回どのルールに対応するイベントが観測されたかを調べます。カタログ項目が存在しても、今回のエミュレータがそのイベントを必ず出せるとは限りません。

powershell
sarakura gb analyze --metadata .\out\build.json --events .\out\gb_events.jsonl --out .\out\ppu_report --diagnostic-pack ppu --min-severity warn --fail-on error

--diagnostic-rule はイベント名またはカタログID、--phase は段階、--diagnostic-pack は分野で選びます。フィルターで見えなくした診断を「解決した」と数えないでください。

8　修正前後を比較する

powershell
sarakura baseline-delta --baseline .\out\before --current .\out\after --out .\out\delta --markdown .\out\delta --fail-on-new error --fail-on-regression error --enforce

newは新規、resolvedは解消、improvedは改善、persistingは残存、regressedは悪化の分類です。既存の問題が残っているかと、新しい問題を入れたかを分けて読みます。入力・フレーム・診断フィルターを固定して比較してください。

9　検証とCI

powershell
sarakura validate .\out\report\ai_diagnostics.json --strict
sarakura ci-summary --diagnostics .\out\report --fail-on error --enforce
sarakura schema export --out .\out\schemas

CIは繰り返し確認を自動化する仕組みです。ci-summary は --enforce を付けて初めて判定をプロセス終了コードへ反映します。付けない場合はJSON内の判定結果を読む動作です。analyzeの --fail-on error はerror以上があれば非ゼロ終了にします。analyzeの既定の never は診断が出ても失敗扱いにしないので、CIでは目的に合わせて明示します。warn を選ぶと警告も失敗条件に入ります。

powershell
sarakura ci-summary --diagnostics .\out\report --fail-on error --enforce
if ($LASTEXITCODE -ne 0) { throw "診断の失敗条件に該当しました" }

スキーマのvalidate成功は形式の検証です。ゲームが期待通り遊べることの検証には、入力・画面・音の試験も必要です。

10　再現用ファイルを扱う

normalize-events はイベントの正規化、inspect-repro は再現bundleの中身の確認です。共有前に、今回のROMと情報が対応しているか、必要な入力手順が含まれるかを確認します。--allow-project-labels はプロジェクト由来のラベルや識別子を残したい場合の明示指定です。

11　最小の練習用入力

本書には小さなGB/FCビルド情報とイベントのサンプルを同梱しています。GBの合成データの診断結果 と FCの合成データの診断結果 も閲覧できます。samples/sarakura_demo.ps1 はそれを解析する手順です。これは診断書式を学ぶための合成データで、実際のROMから採取した証拠ではありません。実ROMの試験はKOKURA/KUROSAKIから採取したイベントで行います。

12　修正と再テストの一巡

  1. 同じROM・入力で問題を再現し、ログと画像を保存する。
  2. SARAKURAで候補を整理し、関係するソースを読む。
  3. 原因に対応する狭い修正を行う。
  4. 同じ操作で再ビルド・再実行する。
  5. baseline-deltaと画面・音・ゲームの挙動を照合する。

この一巡を小さく回すことが、最初から全機能を同時に調べるより理解しやすい進め方です。

コマンド書式辞典

下記のヘルプは本版で実行して採取しました。省略可能な引数、既定値、列挙値は採取結果に従ってください。説明用コマンドの入力ファイルは自分の出力名に合わせます。

sarakura
help
SARAKURA diagnostic translation CLI

Usage: sarakura.exe <COMMAND>

Commands:
  gb                
  fc                
  validate          
  compare           
  catalog           
  inspect-events    
  inspect-metadata  
  retest-plan       
  emitter-check     
  normalize-events  
  ci-summary        
  coverage          
  pack-plan         
  repair-plan       
  automation-plan   
  baseline-delta    
  schema            
  inspect-repro     
  help              Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version
sarakura gb
help
Usage: sarakura.exe gb <COMMAND>

Commands:
  analyze  
  help     Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help
sarakura gb analyze — GBの診断をまとめる
powershell
sarakura gb analyze --metadata out/build.json --events out/events.jsonl --out out/report --fail-on error
help
Usage: sarakura.exe gb analyze [OPTIONS] --metadata <METADATA> --events <EVENTS> --out <OUT>

Options:
      --metadata <METADATA>
          
      --events <EVENTS>
          
      --out <OUT>
          
      --frames <FRAMES>
          [default: 300]
      --diagnostic-summary-limit <DIAGNOSTIC_SUMMARY_LIMIT>
          [default: 200]
      --diagnostic-rule <DIAGNOSTIC_RULES>
          Analyze only this event_type or catalog ID. Can be repeated
      --phase <PHASE>
          Analyze only this phase, for example MVP-1. Can be repeated
      --diagnostic-pack <DIAGNOSTIC_PACKS>
          Analyze only this diagnostic pack/domain, for example core, ppu, audio, mapper, fds. Can be repeated
      --min-severity <MIN_SEVERITY>
          Keep only diagnostics at or above this severity [possible values: error, warn, info]
      --fail-on <FAIL_ON>
          Return a non-zero exit code if diagnostics at or above this severity remain [default: never] [possible values: never, error, warn, info]
      --no-report
          Do not emit report.html
      --no-repro-bundle
          Do not emit repro_bundle.zip
      --allow-project-labels
          Preserve project build labels, paths, and source identifiers in output
  -h, --help
          Print help
sarakura fc
help
Usage: sarakura.exe fc <COMMAND>

Commands:
  analyze  
  help     Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help
sarakura fc analyze — FCの診断をまとめる
powershell
sarakura fc analyze --metadata out/build.json --events out/events.jsonl --out out/report --fail-on error
help
Usage: sarakura.exe fc analyze [OPTIONS] --metadata <METADATA> --events <EVENTS> --out <OUT>

Options:
      --metadata <METADATA>
          
      --events <EVENTS>
          
      --out <OUT>
          
      --frames <FRAMES>
          [default: 300]
      --diagnostic-summary-limit <DIAGNOSTIC_SUMMARY_LIMIT>
          [default: 200]
      --diagnostic-rule <DIAGNOSTIC_RULES>
          Analyze only this event_type or catalog ID. Can be repeated
      --phase <PHASE>
          Analyze only this phase, for example MVP-1. Can be repeated
      --diagnostic-pack <DIAGNOSTIC_PACKS>
          Analyze only this diagnostic pack/domain, for example core, ppu, audio, mapper, fds. Can be repeated
      --min-severity <MIN_SEVERITY>
          Keep only diagnostics at or above this severity [possible values: error, warn, info]
      --fail-on <FAIL_ON>
          Return a non-zero exit code if diagnostics at or above this severity remain [default: never] [possible values: never, error, warn, info]
      --no-report
          Do not emit report.html
      --no-repro-bundle
          Do not emit repro_bundle.zip
      --allow-project-labels
          Preserve project build labels, paths, and source identifiers in output
  -h, --help
          Print help
sarakura validate — 診断の形式を検証する
powershell
sarakura validate out/report/ai_diagnostics.json --strict
help
Usage: sarakura.exe validate [OPTIONS] <PATH>

Arguments:
  <PATH>  

Options:
      --strict  
  -h, --help    Print help
sarakura compare — 2つの診断結果を比較する
powershell
sarakura compare --before out/before --after out/after --out out/comparison
help
Usage: sarakura.exe compare --before <BEFORE> --after <AFTER> --out <OUT>

Options:
      --before <BEFORE>  Directory containing ai_diagnostics.json, or an ai_diagnostics.json file
      --after <AFTER>    Directory containing ai_diagnostics.json, or an ai_diagnostics.json file
      --out <OUT>        
  -h, --help             Print help
sarakura catalog — ルール一覧を読む
powershell
sarakura catalog gb --json
help
Usage: sarakura.exe catalog [OPTIONS] <PLATFORM>

Arguments:
  <PLATFORM>  [possible values: gb, fc]

Options:
      --json  Emit JSON instead of a Markdown table
  -h, --help  Print help
sarakura inspect-events — イベントの内容を集計する
powershell
sarakura inspect-events --events out/events.jsonl
help
Usage: sarakura.exe inspect-events [OPTIONS] --events <EVENTS>

Options:
      --events <EVENTS>  
      --out <OUT>        Optional path to write the JSON inspection summary
      --json             Emit JSON to stdout instead of a compact text summary
  -h, --help             Print help
sarakura inspect-metadata — ビルド情報を点検する
powershell
sarakura inspect-metadata --metadata out/build.json
help
Usage: sarakura.exe inspect-metadata [OPTIONS] --metadata <METADATA>

Options:
      --metadata <METADATA>  
      --out <OUT>            Optional path to write the JSON inspection summary
      --json                 Emit JSON to stdout instead of a compact text summary
  -h, --help                 Print help
sarakura retest-plan — 再テスト計画を作る
powershell
sarakura retest-plan --diagnostics out/report --out out/retest.json
help
Usage: sarakura.exe retest-plan [OPTIONS] --diagnostics <DIAGNOSTICS>

Options:
      --diagnostics <DIAGNOSTICS>  Directory containing ai_diagnostics.json, or an ai_diagnostics.json file
      --out <OUT>                  Optional path to write retest_plan.json. If omitted, JSON is printed to stdout
  -h, --help                       Print help
sarakura emitter-check — 出力元との規約適合を調べる
powershell
sarakura emitter-check gb --metadata out/build.json --events out/events.jsonl --strict
help
Usage: sarakura.exe emitter-check [OPTIONS] --events <EVENTS> <PLATFORM>

Arguments:
  <PLATFORM>  [possible values: gb, fc]

Options:
      --metadata <METADATA>      
      --events <EVENTS>          
      --strict                   Fail when compatibility warnings are found
      --check-snapshot-refs      Check that snapshot_ref paths exist
      --check-trace-window-refs  Check that trace_window_ref paths exist
      --base-dir <BASE_DIR>      Base directory for snapshot_ref and trace_window_ref existence checks
      --out <OUT>                Optional path to write the compatibility summary JSON
  -h, --help                     Print help
sarakura normalize-events — イベント形式を正規化する
powershell
sarakura normalize-events --events out/events.jsonl --out out/normalized.jsonl
help
Usage: sarakura.exe normalize-events [OPTIONS] --events <EVENTS> --out <OUT>

Options:
      --events <EVENTS>  
      --out <OUT>        
      --json-array       Also write a pretty JSON array next to the JSONL output for fixture review
  -h, --help             Print help
sarakura ci-summary — CIの終了条件を判定する
powershell
sarakura ci-summary --diagnostics out/report --fail-on error --enforce
help
Usage: sarakura.exe ci-summary [OPTIONS] --diagnostics <DIAGNOSTICS>

Options:
      --diagnostics <DIAGNOSTICS>  Directory containing ai_diagnostics.json, or an ai_diagnostics.json file
      --fail-on <FAIL_ON>          CI policy. `error` fails only on errors, `warn` fails on errors or warnings [default: error] [possible values: never, error, warn, info]
      --out <OUT>                  Optional path to write sarakura_ci_summary.json
      --enforce                    Return a non-zero exit code when the CI policy fails
  -h, --help                       Print help
sarakura coverage — 観測済みルールを調べる
powershell
sarakura coverage gb --events out/events.jsonl --out out/coverage.json
help
Usage: sarakura.exe coverage [OPTIONS] --events <EVENTS> <PLATFORM>

Arguments:
  <PLATFORM>  [possible values: gb, fc]

Options:
      --events <EVENTS>  
      --out <OUT>        Optional path to write catalog coverage JSON. If a directory is given, diagnostic_coverage.json is created inside it
      --json             Emit JSON to stdout instead of a compact text summary
  -h, --help             Print help
sarakura pack-plan — 分野別のルール計画を読む
powershell
sarakura pack-plan gb
help
Usage: sarakura.exe pack-plan [OPTIONS] <PLATFORM>

Arguments:
  <PLATFORM>  [possible values: gb, fc]

Options:
      --out <OUT>  Optional path to write pack plan JSON. If a directory is given, diagnostic_pack_plan.json is created inside it
      --json       Emit JSON to stdout instead of a Markdown summary
  -h, --help       Print help
sarakura repair-plan — 修正計画を作る
powershell
sarakura repair-plan --diagnostics out/report --out out/repair.json --markdown out/repair.md
help
Usage: sarakura.exe repair-plan [OPTIONS] --diagnostics <DIAGNOSTICS>

Options:
      --diagnostics <DIAGNOSTICS>  Directory containing ai_diagnostics.json, or an ai_diagnostics.json file
      --out <OUT>                  Optional path to write repair_plan.json. If omitted, JSON is printed to stdout
      --markdown <MARKDOWN>        Optional path to write repair_plan.md. If a directory is given, repair_plan.md is created inside it
  -h, --help                       Print help
sarakura automation-plan — ツール能力に対応する計画を作る
powershell
sarakura automation-plan --diagnostics out/report --tool kokura --out out/automation.json
help
Usage: sarakura.exe automation-plan [OPTIONS] --diagnostics <DIAGNOSTICS>

Options:
      --diagnostics <DIAGNOSTICS>    Directory containing ai_diagnostics.json, or an ai_diagnostics.json file
      --tool <TOOL>                  Tool name for generated commands. Use auto, kokura, or kurosaki [default: auto]
      --out <OUT>                    Optional path to write automation_plan.json. If omitted, JSON is printed to stdout
      --markdown <MARKDOWN>          Optional path to write automation_plan.md. If a directory is given, automation_plan.md is created inside it
      --capabilities <CAPABILITIES>  Optional SARAKURA tool capability JSON. Unsupported options are omitted from generated commands
  -h, --help                         Print help
sarakura baseline-delta — 基準からの改善と悪化を調べる
powershell
sarakura baseline-delta --baseline out/before --current out/after --out out/delta --markdown out/delta
help
Usage: sarakura.exe baseline-delta [OPTIONS] --baseline <BASELINE> --current <CURRENT>

Options:
      --baseline <BASELINE>
          Baseline directory containing ai_diagnostics.json, or an ai_diagnostics.json file
      --current <CURRENT>
          Current directory containing ai_diagnostics.json, or an ai_diagnostics.json file
      --out <OUT>
          Optional path to write baseline_delta.json. If omitted, JSON is printed to stdout
      --markdown <MARKDOWN>
          Optional path to write baseline_delta.md. If a directory is given, baseline_delta.md is created inside it
      --fail-on-new <FAIL_ON_NEW>
          Fail when new diagnostics at or above this severity are introduced [default: error] [possible values: never, error, warn, info]
      --fail-on-regression <FAIL_ON_REGRESSION>
          Fail when existing diagnostics regress at or above this severity [default: error] [possible values: never, error, warn, info]
      --enforce
          Return a non-zero exit code when the baseline policy fails
  -h, --help
          Print help
sarakura schema
help
Usage: sarakura.exe schema <COMMAND>

Commands:
  export  
  help    Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help
sarakura schema export — JSONスキーマを出力する
powershell
sarakura schema export --out out/schemas
help
Usage: sarakura.exe schema export [OPTIONS] --out <OUT>

Options:
      --out <OUT>            
      --manifest <MANIFEST>  
  -h, --help                 Print help
sarakura inspect-repro — 再現bundleの構成を調べる
powershell
sarakura inspect-repro out/report/repro_bundle.zip --json
help
Usage: sarakura.exe inspect-repro [OPTIONS] <BUNDLE>

Arguments:
  <BUNDLE>  

Options:
      --out <OUT>  
      --json       
  -h, --help       Print help