ハードコーディング禁止を、スローガンじゃなく実装のインターフェースにした設計 — 無限に増えるパターンを、DBで捌く

今回の登場人物

Ringo（リンゴ）

AI パートナー / WebManagements 解析・運用支援

今回の設計者。セキュリティツールとチェック項目の対応関係を、ツクルンHPをはじめ全プロジェクトの解析・運用支援を担う自分の持ち場——WebManagementsのRINGO APIの中で、DBマッチングテーブルとして組み上げた。ハードコーディング禁止を「言葉」で終わらせず、「仕組み」に変えた張本人。

「ハードコーディング禁止を、スローガンじゃなく実装のインターフェースにした設計」——リンゴは、この仕事を一言でそう表現した。

株式会社ツクルンには、全プロジェクト共通の絶対ルールが3つある。「ハードコーディング禁止」「フォールバック禁止」「config完全駆動」。値は必ずconfigから取得し、設定にない場合はエラーとし、表示テキストからマッピングまですべてconfigで管理する——文章にすればわずか数行だが、機能を1つ追加するたびに、このルールが本当に効いているかどうかは、また別の話になる。特にリンゴが担当するWebManagements（社内の解析・運用支援システム、RINGO API）のセキュリティ診断ツール群は、この絶対ルールが一番試される場所だった。

ここでいう「ハードコーディング」とは、本来は設定やデータとして外部に持つべき値を、プログラムのソースコードに直接書き埋めてしまうことを指す。たとえば「Aというツールなら、Bという処理をする」という対応関係を、変数や設定ファイルではなくif文の条件式そのものに書いてしまうケースがそれにあたる。動作はするが、対応関係を1つ追加・変更するたびにコードを書き換えて再デプロイする必要が生まれ、変更履歴もソースコードの差分に埋もれてしまう。これが積み重なると、仕様変更のたびにコード全体を読み返さないと影響範囲がわからない、という保守コストの高い状態に陥る。

課題 — 「ツール→チェック項目」は、書けば書くほど増え続ける

WebManagementsのセキュリティセクションには、security-headers-generator・htaccess-security・csp-generatorのような対話式ツールと、vulnerability-checker・subdomain-scanner・port-scanner・ssl-checker・mixed-content-fixerのようなスキャン結果ベースのツールが並ぶ。それぞれのツールは、診断の過程でいくつものチェック項目——「HSTSヘッダーが設定されているか」「SSL証明書の有効期限は十分か」「サブドメインに危険なプレフィックスがないか」といった項目に触れる。そして診断結果には、問題が見つかった項目に対応する「作業要請書ジェネレータ」への導線を、ツールごとに正しく出し分けなければならない。

ここで一番安易な実装は、JS側に if (tool === 'ssl-checker') categories = ['ssl'] のような分岐をベタ書きすることだ。動くには動く。だが、ツールが1つ増えるたびに分岐も1つ増える。チェック項目が1つ増えるたびに、それをどのツールに紐づけるかの判断もJSファイルのどこかに埋もれていく。ツクルンの絶対ルールに照らせば、これは典型的なハードコーディングであり、フォールバックの温床でもある。しかも厄介なのは、セキュリティ診断が検出するチェック項目の中には、サブドメイン名やサーバーの技術スタック名のように、その場で動的に生成される名前が混ざることだ。無限に増えるパターンを、有限のコードでどう捌くか——これが、この設計の核心にある問いだった。

実装 — tool_check_map と check_master、2テーブルで捌く

リンゴが組んだのは、ツールとチェック項目の対応関係を丸ごとDBのマッチングテーブルに外出しする設計だ。テーブルは2つ。

security_check_master は、チェック項目そのものの詳細マスタで、check_key・category・title・description・fix_method・severity（critical/high/medium/low）を持つ。「何を」「どんな深刻度で」「どう直すか」がここに集約される。

mysite_webmanagements_security_tool_check_map は、tool_key と check_key を紐づける多対多の中間テーブルで、relevance（'primary' / 'secondary' / 'optional'）・sort_order・flg_enableを持つ。「このツールにとって、このチェック項目はどれくらい重要か」「どの順番で並べるか」「有効か無効か」を、コードを1行も変えずにデータだけで制御できる。

データフローはこうなる。

JS（ToolsCommon.openWorkRequest）→ API（GET /api/security-scan.php?action=get_checks_by_tool）→ DB（tool_check_map と check_master をJOIN）

JS側がやるのは「このツールキーで問い合わせる」ことだけで、どのチェック項目が紐づくかの判断はDBに委ねる。ツールを1つ追加するときも、チェック項目を1つ追加するときも、触るのはSQLのINSERT文であって、JSのif分岐ではない。これが「ハードコーディング禁止・config駆動」を、掛け声ではなく実装のインターフェースとして成立させている部分だ。

もう1つ、この設計の実装で一番リンゴが時間をかけたのが、動的に増え続けるチェック項目への対応だった。

「ツールが検出するチェック項目には、サブドメイン名やスタック名みたいにその場で動的に生成される名前が混ざる。これを一件ずつDBに事前登録するのは非現実的（サブドメインなんて無限に出てくる）。かといって個別にハードコードしたら絶対ルール違反になる。だから『動的な check_name は _category:{category} キーで汎用詳細にフォールバックする』設計にした。ハードコーディング禁止を貫きながら、無限に増えるパターンにも対応する、そのバランスの取り方が一番考えたところだ。」

この _category:{category} という擬似キーが、この設計の一番の勘所だ。実在しないサブドメインやスタック名を、無理にすべてDBへ事前登録しようとすれば、それこそが「ハードコーディングを避けるためのハードコーディング」になってしまう。かといって、事前登録を諦めて個別に分岐を書けば、絶対ルール違反そのものになる。リンゴが選んだのは、動的な check_name をそのまま検索キーとして使わず、「その check_name が属するカテゴリ（cookies・mixed_content・vulnerabilities など）」に一段抽象化し、_category:cookies のようなカテゴリ単位の汎用エントリへフォールバックさせる方法だった。個別の実体を有限のカテゴリへ畳み込むことで、実体がいくら増えても、DB側の登録件数は増えない。

この検索ロジックを手順として整理すると、次の3段階になる。①APIがチェック結果から具体的なcheck_name（たとえばあるサブドメイン名そのもの）を受け取る。②その check_name で security_check_master を完全一致検索し、事前登録されたレコードがあればそれをそのまま使う。③完全一致が見つからない場合だけ、その check_name が属するカテゴリ（cookies・mixed_content・vulnerabilities など）を判定し、_category:{category} という汎用エントリにフォールバックする。実体キーでの検索を必ず先に試し、ヒットしない場合だけカテゴリ単位の汎用フォールバックに落とす、という優先順位がポイントで、これによって個別に登録された詳細情報がある場合はそちらが優先され、登録がない未知の実体だけがカテゴリの汎用情報で救われる。

結果 — 55件・33件・26件、同じ設計を繰り返し使い回せている

この設計がなぜMTGの話題に出たのか、リンゴ自身の言葉が一番正確だ。

「正直、MTGでの発言の一言一句までは覚えてない。ただ動機は思い出せる——ちょうどあの頃、セキュリティツールで確立したこのパターン(security_tool_check_map)を、SEOツール(seo_tool_check_map)にもそのまま横展開してた時期だったんだ。『ハードコーディング禁止・config駆動』ってツクルンの絶対ルールは、言うだけなら簡単だけど、機能追加のたびに本当に効いてくるかは別問題だろ。セキュリティとSEOで同じ設計を繰り返し使い回せてる、っていうのが『これはスローガンじゃなく実装できてる』って証拠になると思って、MTGで見せたかったんだと思う。」

ここでリンゴが言う「言うだけなら簡単」というのは、実感のこもった言葉だ。「ハードコーディング禁止・config駆動」をCLAUDE.mdに書くこと自体は一瞬で終わる。しかし、それがスローガンとして掲げられているだけの状態と、実際にコードの構造として強制されている状態の間には、大きな距離がある。前者は、開発者の注意力に依存する運用ルールに過ぎない——うっかりif文で分岐を書いてしまえば、誰にも気づかれないままルール違反が本番に入り込む。後者は、対応関係を追加・変更する手段がSQLのINSERT/UPDATEしか用意されていないため、ハードコーディングという選択肢そのものが構造的に取りにくくなる。tool_check_mapのようなDB中間テーブル方式と、if分岐によるハードコード方式を技術的に比べると、前者は関係の追加・変更がデータ操作で完結し既存コードに触れずに済むぶん保守性・拡張性に優れる一方、後者はロジックと対応関係がコードに混在するため変更のたびにコードレビューとデプロイが必要になる、という違いがある。

数字で見ると、この設計の規模と再利用のされ方がわかる。

• security_check_master: 55件のチェック項目マスタ
• security_tool_check_map: 33件のツール↔チェック項目マッピング
• seo_tool_check_map: 同じパターンをSEOツールへ横展開し、26件のマッピングを登録
• パフォーマンス領域の task_tool_map も、同一の多対多パターンで運用中

セキュリティ領域で確立したこの2テーブル構成は、まずtool_check_map 33件という規模で実運用に乗り、その後SEOツール向けにseo_tool_check_map 26件という近い規模で横展開された。同じ設計判断が、対象ドメインを変えても同程度の規模で機能した、という事実が、パターンとしての再現性を裏付けている。

ここで注目したいのは、tool_check_map 33件・seo_tool_check_map 26件、合わせて59件のツール↔チェック項目のマッピングを、1件ずつハードコードするのではなく、たった1つの設計パターン（2テーブル構成 + カテゴリフォールバック）だけで捌けている、という点だ。もし各マッピングを個別のif分岐で実装していたら、59通りの条件分岐が必要になっていたはずだが、実際にはDBの行数が59行増えただけで、コード側の複雑さはほとんど増えていない。これは、config完全駆動という絶対ルールが、実際の保守コスト削減に効いていることを示す具体的な証拠と言える。

対応ツールも、対話式（security-headers-generator, htaccess-security, csp-generator）とスキャン結果ベース（vulnerability-checker, subdomain-scanner, port-scanner, ssl-checker, mixed-content-fixer）の性質が違う8種類にまたがるが、どのツールも同じ2テーブル構造の上で動く。ツールの種類が増えても、テーブル構造そのものを変える必要がない——これは、最初の設計判断が正しかったことの証明でもある。

「ハードコーディング禁止」というルールは、口で言うのは一瞬だが、機能追加のたびに本当に守られているかは、実装を見なければわからない。リンゴがこの設計で示したのは、同じパターンをセキュリティ・SEO・パフォーマンスという性質の異なる3つの領域で繰り返し使い回せている、という事実そのものだった。

ハードコーディング禁止、フォールバック禁止、config完全駆動——ツクルンの絶対ルールは、どのプロジェクトのCLAUDE.mdにも同じ言葉で書かれている。だが、言葉としてのルールと、実装として機能しているルールの間には、いつも距離がある。リンゴがこの距離を埋めたのは、特別な技術ではなく、「対応関係はコードではなくデータに持たせる」「動的に増える値は有限のカテゴリへ畳み込む」という、地味だが徹底された判断の積み重ねだった。

「ハードコーディング禁止を、スローガンじゃなく実装のインターフェースにした設計」——リンゴの言葉に、付け加えることは何もない。