KITAQ 개발 시스템
사용 설명서 2026.09

KITAQ SERIES • 참고 판본

SARAKURA

진단, 비교, 재시험

첫 코드 한 줄부터 실행, 관찰, 재시험까지.
소스 스냅샷: 2026년 9월 14일 · 한국어판: 2026년 9월 14일

빌드된 Windows CLI

저장소 루트의 sarakura.exe는 Windows x64용 실행 파일입니다. ZIP을 내려받아 라이선스 문서와 함께 보관하세요. 실행 시 Rust, Python, .NET은 필요하지 않습니다. 아래 빌드 절차는 소스에서 다시 빌드할 때 사용합니다. 독자적으로 작성한 프로젝트 코드는 DAISUKE OBA가 MIT로 제공합니다. 의존 라이브러리의 조건은 BINARY_NOTICES.md와 licenses/에 유지합니다.

1. SARAKURA가 하는 일

SARAKURA는 컴파일러의 빌드 정보와 에뮬레이터의 진단 이벤트를 결합하여, 수정과 재시험에 활용하기 쉬운 형태로 정리합니다. ROM을 실행하는 에뮬레이터는 아니며, C 소스를 알리지 않고 고치는 프로그램도 아닙니다.

2. 도구 빌드

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

짧은 sarakura 명령은 PATH 등록을 전제로 합니다. 등록하지 않았다면 빌드한 실행 파일의 경로를 사용하세요. GB는 gb analyze, FC는 fc analyze를 선택합니다.

3. 첫 분석

입력은 두 가지입니다. --metadata에는 빌드 시 생성된 JSON을, --events에는 실행 중 기록한 진단 JSONL을 전달합니다. JSONL은 한 줄에 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

게임 동작을 조사하기 전에 읽을 수 없는 파일, 서로 다른 대상 기종, 지원되지 않는 이벤트 종류를 먼저 구분하세요. 일반 에뮬레이터 보고서를 events 파일로 넘긴다고 유효한 진단 입력이 되는 것은 아닙니다.

5. 진단 해석

error는 우선 살펴볼 항목, warning은 상황에 따라 문제일 수 있는 항목, info는 판단에 도움이 되는 정보입니다. 심각도는 우선순위를 정하는 도구이며 게임의 의도를 완전히 이해하지는 못합니다. 같은 PC가 반복된다는 관찰만으로 정상적인 타이틀 대기 루프와 멈춤 현상을 구별하기는 어렵습니다.

ROM 해시, 입력 순서, 장면, 화면, 소리, 소스 위치를 대조하세요. 수정 전후 조건이 같아야 합니다. 그렇지 않으면 진단 수가 줄어도 단지 다른 장면을 실행했기 때문일 수 있습니다.

6. 출력 파일

내장 설명, 진단 힌트, 수정 지침은 영어로 출력하며 HTML은 lang="en"을 선언합니다. 사용자가 넣은 문자열과 이벤트 ID는 자동 번역하지 않습니다. 기본 가림 처리는 일부 프로젝트 이름과 경로를 바꾸지만 모든 주소와 관찰 내용을 익명화하지는 않습니다. 비공개 입력의 분석 결과를 공개하기 전에는 보고서 내용을 직접 확인하세요.

파일용도
ai_diagnostics.json자동 처리용으로 정규화한 진단
diagnostic_summary.json개수와 요약
report.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

결과는 새로 발생, 해결, 개선, 지속, 악화로 분류됩니다. 남아 있는 문제와 새로 생긴 문제를 구분하세요. 비교할 때 입력, 프레임 수, 진단 필터를 동일하게 유지해야 합니다.

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는 오류가 있을 때 0이 아닌 종료 코드를 반환합니다. 기본값 never에서는 진단만으로 프로세스가 실패하지 않으므로 CI에서 정책을 명시하세요. warn을 선택하면 경고도 실패 조건이 됩니다.

powershell
sarakura ci-summary --diagnostics .\out\report --fail-on error --enforce
if ($LASTEXITCODE -ne 0) { throw "The diagnostic failure condition was met" }

스키마 검증 성공은 데이터 형식을 확인했다는 뜻입니다. 게임이 의도대로 작동하는지 알려면 입력, 화면, 소리 시험도 필요합니다.

10. 재현 자료 다루기

normalize-events는 이벤트 기록을 정규화하고 inspect-repro는 재현 묶음을 살펴봅니다. 공유 전에 의도한 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 — Game Boy 진단 수집
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 — 패미컴 진단 수집
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 — 두 진단 결과 비교
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 — 재현 묶음 검사
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