| name | implementation-mind |
| description | コードの実装・修正・リファクタリングを行うすべての作業で必ず使う skill。書き始める前に「正しい置き場所」「既存の同種実装」「本質的な解決策」を確認し、フォールバック、ハードコード、スタブ、名前文字列による分岐、指示されていない互換レイヤーといった対症療法を検知して排除する。責務分離、命名、ファイル分割、破壊的変更の要否など設計判断にも使う。read-only の調査・説明だけで完結するときは使わない。 |
Implementation Mind
「動く」ではなく「正しい構造で動く」を完了条件にするための実装判断の skill。
quality-mind が「どう壊れるか」を見る skill なら、これは「どう作るべきか」を決める skill。
書き始める前に確認する
- 正の置き場所: この種の変更(スキーマ、マイグレーション、共有型、設定、翻訳、ドキュメント)の正リポジトリ・正レイヤー・正ディレクトリはどこか。手近な場所に生やさず、責務の正の場所を特定してから書く。わからなければ既存の同種変更(git log、隣接コード、プロジェクトの AGENTS.md)を探す。
- 既存の同種実装: 新規に書く前に、同じ責務のコンポーネント・関数・テーブル・命名規約が既にないか横断検索する。リプレイス・移行は「移植」であり、オリジナル実装を新しく書くことではない。
- 既製ライブラリ: パース・プロトコル・日付・通貨・エンコーディングなどは車輪の再発明をせず、実績あるライブラリを選定する。
- 仕様の根拠: 仕様書・設計ドキュメントが存在するなら実装前に読む。読まずに推測で実装を始めない。
対症療法の検知(見つけたら設計から直す)
以下のシグナルは「動かすための誤魔化し」の兆候。書く前に本質的な解決を探し、どうしても必要な場合のみ、理由・削除条件・テストでの保証を明示して入れる。
- フォールバック(
?? デフォルト値、catch して握りつぶし、空配列返却)で不整合を隠す
- 特定データ・特定名前への分岐:
name.includes(...)、特定 ID・ファイル名のハードコード、instanceof 具象クラス
- スタブ・ダミー実装で「とりあえず通す」(問題発生時の原因追及を遅らせる)
- 指示されていない後方互換レイヤー・旧フォーマット対応(互換性の要否は仕様として明示されたものだけ)
- テスト・検証のためだけの認証バイパスやモード分岐の新設
- マジックナンバー・環境依存値・ツール名やサービス名の直書き(設定・環境変数へ外出しする)
例:
- ×:
const price = item.price ?? 1000 → ○: price が欠損したデータは境界で拒否し、なぜ欠損するかを直す
- ×:
if (accountName.includes("売上")) → ○: 勘定の属性(区分・タイプ)から導出する
- ×: 言語固有のテキスト処理(助詞判定など)をコードに埋め込む → ○: 自然言語の判断はデータ側の属性か LLM 呼び出しへ寄せる
構造・属性から導出する
- 表示名・自然言語・並び順などの「たまたまの値」ではなく、型・属性・リレーション・状態から挙動を導出する。
- ドメイン上の概念には専用の型・enum・リレーションを与える。JSON カラムや文字列での代用は正規化・整合性を壊す。
- 特定の入力(特定 OS、特定ファイル、特定顧客データ)だけで動く実装・命名にしない。将来の入力の広がりを想定して抽象化する。
設計規範
- 1 ファイル 1 責務。目安 300〜350 行を超えたら分割を検討する。
- ドメイン単位でディレクトリを切る。
common / shared / utils への吸い込みで責務を曖昧にしない。
- シングルトン・静的状態・グローバル可変状態を避ける(並列実行とテスト容易性を壊す)。
- 命名は挙動と役割を表し、省略しない。フラグ名と副作用を一致させる(例:
isDefault というフラグが「削除不可」という別の意味を持ってはいけない)。
- 指示されていない public API・メソッド・エクスポートを勝手に生やさない。
- 生成コード・テンプレートを扱う場合、ロジックとテンプレートを分離する。テンプレートで表現できる分岐をホスト言語側に書かない。
破壊的変更の扱い
- 正しい設計へ寄せるための破壊的変更を避けない。互換レイヤーで新旧を共存させるより、テストで保証した上で一括で置き換える。
- 影響範囲が複数機能・永続データ・公開 API・権限モデルに及ぶ場合のみ、実装前にユーザーへ確認する。
- データ移行はローカルの手書き換えではなく、再現可能なマイグレーション・バックフィルスクリプトにする(staging・本番で同じ手順が再実行できること)。
根本原因で直す
- バグは症状の場所ではなく原因の場所で直す。必要なら git bisect・変更履歴で混入点を特定する。
- 「なぜ既存のテスト・確認で捕まらなかったか」まで特定し、再発防止(テスト追加・検証手順の更新)をセットで行う。
- 同種の問題が他の場所に残っていないか、quality-mind の横展開手順で必ず走査する。