| name | critique-code |
| description | 変更 diff（または指定モジュール）を「抽象度・Doc 境界・テスト方針・読みやすさ」の 5 軸で批評するレポートを返す。ゲーム実装・見本づくりの完了条件として、報告の前の自己批評に使う。まとまった実装を終えたとき、コミットや PR を出す前、「レビューして」「これで良い？」と言われたときに使う。 |
| sync | 2026-08-11T00:00:00.000Z |
critique-code — コードを批評する
引数(任意): 対象(diff / ファイル名 / モジュール名)。省略時は git diff(未コミットの変更全体)。
このエンジンの売りは「AI が短時間で書いても、壊れにくく・壊れがすぐ検知でき・
人間にも読みやすいコード」が出てくること。このスキルはそれを謳い文句でなく
検査項目にする。修正はしない — 批評だけ返し、直すかどうかは呼び出し側が決める。
手順
- 対象を読む(
git diff か指定ファイル)。周辺コードも開き、変更が
「その場所の書き方」になじんでいるかを見る。
- engine の
docs/module-index.md(やりたいこと → モジュールの逆引き)を開き、
変更内容と突き合わせる。
- 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 への言及があるか。呼ぶだけの謎の一行を残していないか。
- レポートを返す: 合格した軸 / 指摘(ファイル:行 と直す案つき、重い順) の順。
指摘ゼロなら「5軸とも合格」と一言で。重箱の隅はレポートを薄めるので書かない —
直したら明確に良くなる指摘だけを返す。
使いどころ
- ゲーム実装・見本(スターター)づくりの依頼文にある「完了条件」の一部として、
報告の前に自己批評 → 指摘を潰してから報告する。
- スターターを templates/ へ昇格させる前の門番(スターターは家族の API 教科書を
兼ねるので、軸1は特に厳しく)。
