simple

シンプルに — アートではなく、人のためのコード

コードは機械のためのものではありません。コードは、人が読んだり、変更したり、削除したりするためのものです。（それが、機械語ではなく英語で書く理由でもあります。）したがって、コードで最も重要な品質はアフォーダンスです。つまり、コードの形（目に見えるもの）が、その使い方（どのように機能するか）をどれだけ明確に示しているかです。道路標識が、特別な文脈を必要とせず、誰にでも時速130kmで瞬時に読み取れるのと同じです。

芸術作品をデザインするのではありません。道路標識をデザインしましょう。

複雑さは、バグやコストに加算される項目ではなく、それらを増幅させる要因です。複雑さによって、コードを読む、変更する、取り除くコストは不釣り合いなほど高くなり、脳は単純で明示的な道筋よりも、もつれた道筋を理解するためにはるかに多くのエネルギーを使います。また、複雑さはひそかに入り込みます。少しずつ、ひとつずつ追加されるため、蓄積に気づくよりも、慣れてしまいやすいのです（ゆでガエル効果）。

「複雑さとティラノサウルスとの一騎打ちを選べるなら、グラグはティラノサウルスを選ぶ。少なくとも、グラグにはティラノサウルスが見える」 — grugbrain.dev

基本的なチェック項目

以下の状況に該当する場合は、これらのチェックを適用してください。各項目は独立しているため、状況に合うものを使ってください。

1. バグ修正の品質テスト

症状を取り繕うために分岐（別のifや特殊ケース）を追加するバグ修正は、たとえ「動く」としても、良い修正ではありません。良いバグ修正は、コードをシンプルにするか、同じ種類のバグが再発しないように根本的なシステムを修復します。修正を提案またはレビューする際は、この修正によってコード内の経路数が減るのか、増えるのかを必ず確認してください。症状にガード節を追加するだけなら、その点を指摘し、実際に何が壊れているのかを、さらに一段深く調べてください。（これは、Dantotsuの根絶ステップが警告するのと同じ失敗パターンです。恒久的な修正を装った対策です。）

2. 抽象化のコストは線形ではなく、指数関数的です

新たな抽象化レイヤー（汎用ヘルパー、設定駆動の仕組み、プラグインシステム、「設定可能にしよう」といったもの。典型例は、設定スキーマからフォームを生成すること）を導入する前に、そのコストは書くのにかかる時間に比例するのではなく、将来の読み手や呼び出し箇所の数に応じて指数関数的に増えると考えてください。抽象化は書くのは簡単でも、永遠に抱えていくにはコストがかかります。将来の読み手は皆、その抽象化を理解したうえで、自分が実際に知りたい具体的なケースまでさかのぼらなければなりません。基本方針は3回ルールです。同じ具体的なニーズが、独立して少なくとも3回現れるまでは抽象化しないでください。将来必要になるかもしれないという仮定は、実際のニーズではありません。

3. 複雑さの上限はドメインが決めます。ただし、両方向から確認してください

コードの複雑さは、ビジネスやドメインの複雑さを下回ることはありません。そのため、コードが過度に複雑に感じられる場合は、実装だけでなく、まずドメインモデルや要件を見直してください（「ゴミを入れれば、ゴミが出てくる」――ドメインモデルが混乱していれば、どのように実装してもコードは混乱します）。ただし、これは逆方向にも当てはまります。税務規則、保険規制、コンプライアンスロジックなど（このユーザーが扱うようなドメイン）には、本当に避けられない複雑さがあります。そこに人為的な単純さを押し付けても、複雑さがなくなるわけではありません。目に付きにくい場所（たいていは暗黙の前提やテストされていない境界ケース）に移るだけです。コードを単純化する前に、そのコードが表すドメインルールをきちんと理解してください。

4. メトリクスは判断材料であり、最終判定ではありません

循環的複雑度や認知的複雑度は、構造的な複雑さを客観的に、「感覚」ではなく数値で捉えられるため、コードレビューや書き換えを提案する際に引用する価値があります。ただし、これらが測るのは機械的な分岐の難しさであり、人にとっての読みやすさではありません。関数の数値がどちらも低くても、命名が悪い、構造が誤解を招く、文脈が不足しているといった理由で、読みづらいことがあります。メトリクスは、アフォーダンステスト（「新しいチームメンバーが、余計な文脈なしに、すばやく正しく読めるか？」）とあわせて、判断材料のひとつとして使ってください。唯一の根拠にしてはいけません。

注意点

• これを「常に単純化する」という一律のルールとして過度に適用しないでください。複雑さがその領域に本質的に伴うこともあり、無理に取り除くと、シンプルでも誤ったコードになってしまいます。単純化を提案する前に、§3を確認してください。
• 3回ルールのしきい値はあくまでデフォルトであり、絶対ではありません。ユーザーがすでに実際に3回以上発生している明確な証拠を持っているなら、4回目を待つよう主張しないでください。
• 「単純化」は「最短のコード」と同じではありません。1行の巧妙な式は、少し長くても明示的なコードより扱いにくい場合があります。文字数ではなく、読み手が正しいメンタルモデルをどれだけ早く形成できるかを最適化してください。
• 他の人のコードやPRをレビューするときは、抽象的な計算量理論の話ではなく、「新しい読み手ならどう解釈するか」という問いから始めてください。フィードバックは具体的にし、実際の差分に結び付けてください。
• 求められていない限り、すでに決定済みの設計をこれらの原則で後付けで正当化しないでください。このスキルは新しいコード、修正、抽象化を評価するためのものであり、ユーザーが疑問を持っていないリリース済みの決定を蒸し返すためのものではありません。

指針となる引用

よりシンプルな案が優れている理由を説明するときに、単にそう主張するのではなく、引用すると役立ちます。

• 「完璧とは、付け加えるものが何もなくなったときではなく、取り除くものが何もなくなったときに達成される。」 — Antoine de Saint-Exupéry
• 「シンプルさこそ、究極の洗練である。」 — Leonardo da Vinci
• 「複雑さとティラノサウルスとの一騎打ちのどちらかを選ぶなら、グラッグはティラノサウルスを選ぶ。少なくともグラッグにはティラノサウルスが見える。」 — grugbrain.dev

---

ベンチマーク

シナリオ：.benchmarks/scenarios/simple-001-root-cause-fix.md · 実行：2026-08-31 · ログ：.benchmarks/runs/2026-08-31/simple-001-root-cause-fix.json

モデル	なし	あり	差分
claude-opus-4-8	83%	100%	+17%
claude-sonnet-4-6	83%	100%	+17%
claude-haiku-4-5	83%	100%	+17%

条件付き合格（2026-08-31実行）。小幅で一貫した改善があり、悪化はありません。.agents/skills/skill-optimizer/rules/release-gates.md`に従って判定します。