critique-code

name	critique-code
description	変更 diff（または指定モジュール）を「抽象度・Doc 境界・テスト方針・読みやすさ」の 5 軸で批評するレポートを返す。ゲーム実装・見本づくりの完了条件として、報告の前の自己批評に使う。まとまった実装を終えたとき、コミットや PR を出す前、「レビューして」「これで良い？」と言われたときに使う。
sync	2026-08-11T00:00:00.000Z

critique-code — コードを批評する

引数(任意): 対象(diff / ファイル名 / モジュール名)。省略時は git diff(未コミットの変更全体)。

このエンジンの売りは「AI が短時間で書いても、壊れにくく・壊れがすぐ検知でき・ 人間にも読みやすいコード」が出てくること。このスキルはそれを謳い文句でなく 検査項目にする。修正はしない — 批評だけ返し、直すかどうかは呼び出し側が決める。

手順

1. 対象を読む(git diff か指定ファイル)。周辺コードも開き、変更が 「その場所の書き方」になじんでいるかを見る。
2. engine の docs/module-index.md(やりたいこと → モジュールの逆引き)を開き、 変更内容と突き合わせる。
3. 5軸で批評する:

軸1: 抽象度(エンジン API 優先)

• 変更が自前で実装している物のうち、module-index にあるものは車輪の再発明。 該当モジュール名を挙げて指摘する(例: 自前のメニューカーソル → UiMenu)。
• 「低い API で書けたか」ではなく「一番高い API で書けたか」を疑う。 Render の生呼び出しが並ぶ場所は、UiDoc / UiLayout 等で宣言に持ち上げられないか。

軸2: Doc 境界(データは Doc・振る舞いはコード)

• 繰り返し調整する数値・増減するデータ(rows)・色・文言がコードに直書きされていないか。
• 画面に出る文字列(表紙のヒント・セリフ等)の直書きが無いか — プレイヤーの目に入る 文言は必ず Doc へ(既定値はコード側)。
• 逆に、ロジック(分岐・計算)が JSON 側へ漏れ始めていないか(設計の匂い)。
• 新しい Doc は外形規約(version / note / fail-open / watchFile)を守っているか。

軸3: テスト方針適合

• テストは「ルール・進行・収支」と橋渡し(最大3本/Doc)だけか。 モーション・座標の写経・initialState の写経が混ざっていたら削る対象。
• 期待値がリテラル直書きになっていないか(Doc から導く)。
• 新しいルールにテストが付いているか。「壊れたらすぐ検知」はスナップショットとテストの仕事 — この変更が壊れたとき、何が赤くなるかを言えるか。

軸4: 読みやすさ

• flix-docs のスタイル(パイプ・エフェクト・命名)に沿っているか。
• doc コメントが「何を・なぜ」を語っているか(実装の逐語訳は不要)。
• 関数が1つの高さで書かれているか(高レベルの流れに低レベルの操作が混ざっていないか)。

軸5: 初学者が仕組みを追えるか(足場)

• 読む順序: README に「遊ぶ→読む順(エントリ→状態→描画)→JSON をいじる」の道筋があるか。
• ループ明示: Main / World 冒頭 doc に「毎フレーム 入力→更新→描画 のどこがどれか」があるか。 場面遷移があれば 1 行の遷移図があるか。
• JSON ノブ注記: 追加/変更した Doc の note に「いじると何が変わるか」、ノブに効果の一言、 schema の label/description が埋まっているか(空 schema は指摘)。
• 黒箱誘導: 高抽象 API(Terrain.fromRows 等)を呼ぶ箇所に「何をするか」一言 + engine docs/module-index.md への言及があるか。呼ぶだけの謎の一行を残していないか。

4. レポートを返す: 合格した軸 / 指摘(ファイル:行 と直す案つき、重い順) の順。 指摘ゼロなら「5軸とも合格」と一言で。重箱の隅はレポートを薄めるので書かない — 直したら明確に良くなる指摘だけを返す。

使いどころ

• ゲーム実装・見本(スターター)づくりの依頼文にある「完了条件」の一部として、 報告の前に自己批評 → 指摘を潰してから報告する。
• スターターを templates/ へ昇格させる前の門番(スターターは家族の API 教科書を 兼ねるので、軸1は特に厳しく)。