回路テスト失敗時のデバッグ手順（CLI版）

このスキルは、レッドストーン回路の自動テストが失敗した際に、原因を切り分けて局所修正するための標準手順です。 修正・再試行は最大5回までです。5回目でも不合格なら、即座に失敗報告を行ってください。

基本姿勢

1. 推測で結果を報告しない: mc-cli の挙動がバグを示した場合は、直ちに作業を中断しユーザーに報告。
2. 生データを確認する: 「たぶん」「おそらく」ではなく、mc-cli get-blocks 等で実際のブロック状態を確認する。
3. 局所修正: 問題のあるブロックのみを修正。安易な全体リセットは禁止。
4. 段階的修正:
   • 1〜2回目の修正は、問題のある1〜3ブロック程度の最小変更に限定する。
   • 3回目以降、最小変更で解決しない場合は、モジュール構造の見直しなど、より大きな変更も許可される。
   • 大きな変更を行う前には、必ず現在の配置状態を保存（バックアップJSONの作成）する。
5. 悪化検知とロールバック: 修正後のテスト結果が前回より悪化した場合（合格数が減少、または新たな失敗が発生）は、直前の配置状態にロールバックする。ロールバックは修正試行回数にカウントしない。
6. 5回で止める: 5回の新規修正試行後も不合格なら、それ以上の修正・配置・テストを禁止。

デバッグ手順

ステップ1: 失敗箇所と期待値を正確に把握

• テスト結果から、どのアサーションが失敗したかを特定する。
• 期待値と実際値を明確に書き出す。
  • 例: 期待 minecraft:redstone_lamp lit=true、実際 lit=false
• 失敗箇所の座標を記録する。

ステップ2: 失敗箇所周辺のブロック状態を取得

• まず --format grid で mc-cli get-blocks を実行し、失敗箇所周辺の全体像（配置構造）を把握する。
  • 推奨範囲: 失敗箇所を中心に前後左右上下2〜3ブロック以上。
• 次に --format json （デフォルト）で同じ範囲を取得し、信号強度（power）、向き（facing）、遅延（delay）などの詳細な状態を確認する。
• 必要に応じて --count と --interval を使い、信号変化のタイミングを追跡する。

ステップ3: 入力側から信号を追跡する

• 出力側から入力側へ向かって、信号がどこで途切れたかを特定する。
• 確認ポイント:
  • 入力レバー/ボタンの powered 状態
  • レッドストーンダストの power と接続状態 (north/south/east/west)
  • リピーターの powered, delay, facing
  • コンパレーターの powered, mode, facing
  • オブザーバーの powered, facing
  • トーチの lit
  • ピストンの extended

ステップ4: プローブを活用する

• 設計時に記録した中間プローブ（リピーター、コンパレーター、接続ポイント等）を参考にする。
• プローブの状態を mc-cli get-blocks で確認し、期待通りの信号が届いているかチェックする。
• 必要に応じて、新たに一時的なプローブ（ランプやダスト）を置いて信号を可視化する。

ステップ5: 向き・接続・更新順序を確認

• repeater, comparator, observer は connects を使って正しく向いているか確認。
• レッドストーンダストが意図した方向に接続しているか確認。
• ピストン系回路では準接続 (QC) やブロック更新順序の影響を疑う。
• タイミングがシビアな場合は、リピーターの遅延を調整する。

ステップ6: 入力を手動で再現する

• mc-cli interact-block コマンドでレバー/ボタンを操作し、回路の反応を直接確認する。
• ボタンの場合は、パルス時間（石系: 1.0秒、木系: 1.5秒）を考慮する。
• 必要に応じて mc-cli get-blocks と mc-cli interact-block を組み合わせて、複数ステップの動作を追跡する。

ステップ7: 局所修正

• 原因が判明したら、最小限のブロックのみを修正する。
• 修正例:
  • 向きが間違っている connects の from/to を修正
  • 遅延が不足しているリピーターの delay を増やす
  • 接続が切れているダストを追加
  • 意図しないQCの影響を受けているブロックを移動
• 修正後はクリーンアップ→配置→テストのサイクルを再実行する。

ステップ8: 5回目で失敗したら停止

• 5回目の試行後も不合格なら、即座に final_status: failure を報告。
• 報告内容:
  • 失敗したテストケース
  • 最終的に確認したブロック状態
  • 推定される原因
  • 試行した修正内容

失敗パターン別の診断ガイド

テストが失敗した場合、まず失敗パターンを分類し、対応するプローブを確認してください。

失敗パターン	確認すべきプローブ	標準的な修正
全入力パターンで出力が変わらない	入力レバー/ボタンの powered、最初の redstone_wire の power	入力機器が動作しているか、connects/attaches の接続先が正しいか確認
特定の入力パターンのみ失敗	該当入力に関わる中間ゲートの出力、分岐点の power	その入力だけに関わる論理ゲート（AND/OR/XOR）の接続や向きを修正
出力が遅れて変化する	経路上の repeater の delay、各段の redstone_wire の power の遷移タイミング	delay を調整、または追加のリピーターで遅延を明示的に確保
出力が意図と逆	redstone_torch の lit、comparator の mode	トーチの入力を反転、コンパレーターの mode（compare/subtract）を確認
一部のビットだけ失敗（加算器など）	該当ビットのキャリー伝播経路、キャリー入力側の power	キャリーの入力元から出力先までの connects と repeater の向きを確認
信号が混線している	隣接する redstone_wire の接続状態 (north/south/east/west)	配線間に不透過ブロックを挿入、または1〜2ブロック以上の隙間を確保
ピストンが動かない	ピストンの extended、準接続範囲のブロック更新、電源側の power	QCの影響を排除、不動ブロックを確認、更新を与えるブロックを追加
ボタン/レバーの操作後、すぐに元に戻る	入力機器の powered、接続先の redstone_wire の power	ボタンの自動リセット挙動を考慮、レバーに置き換えや待機時間の調整

よくある原因と対処法

症状	よくある原因	対処法
出力が全く変わらない	入力レバー/ボタンが動作していない、配線が途切れている	入力状態を確認し、配線の接続を確認
出力が遅れて変化する	リピーター遅延が不足、ブロック更新順序の影響	遅延を調整、リピーターで明示的な遅延を挿入
出力が意図と逆	トーチやコンパレーターのmodeが逆	lit や mode を確認し修正
ピストンが動かない	準接続の影響、不動ブロック、更新が届いていない	QCの影響範囲を確認、更新を与えるブロックを追加
信号が混線している	配線間隔が近すぎる、強動力が漏洩	1〜2ブロック以上の隙間を空ける、不透過ブロックで遮断

コマンドの組み合わせ例

# レバーをON
mc-cli interact-block --pos "10,65,10" --target-state '{"powered": "true"}'

# 200ms待機（4チック）
# （CLI側で待機が必要な場合は、テストYAML内の wait アクションを使用）

# 対象範囲を取得
mc-cli get-blocks --pos1 "8,63,8" --pos2 "15,68,15"

# 取得結果を分析
# 必要に応じて place-blocks で局所修正
mc-cli place-blocks --blocks '<修正用JSON>'

注意

• デバッグ中も knowledges/ 内のファイルは読み込まない。
• ファイルの書き込みは knowledges/ またはセッションごとの一時ディレクトリのみ。
• 推測で原因を決めつけず、必ず mc-cli get-blocks 等のコマンドで確認すること。