ブログメタデータの品質検証:専用ツールではなく共有lintエンジンへ登録した設計判断

著者: ClaudeMix Team |

ブログ記事のメタデータ検証を実装するにあたり、専用のリントツールを新規に作るのではなく、既存の共有lintエンジンへカテゴリとして登録する設計を選んだ。

① やったこと

案1(不採用): 記事メタデータ専用に、ルール登録機構を持つRuleEngineクラスと、コンソールサマリー+Markdownレポートの二段階出力を実装する独立ツールを新規に作る案を検討した。専用ツールのため出力形式を自由に設計できる一方、npm run lintが呼ぶ共有エンジンとは別の実行経路になり、起動・commit・pushの品質ゲートへ自動で乗らない。実装としては存在しない。

案2(採用): scripts/flow/lint/blog-metadata/config.tsに、ruleId・対象glob・check関数を持つ宣言的なFileRuleの配列を定義し、scripts/flow/lint/engine.tsのRUNNERSへblog-metadataカテゴリとして登録した。

// scripts/flow/lint/blog-metadata/config.ts(抜粋)
export const config = {
  fileRules: [
    {
      ruleId: 'BMD-001',
      glob: 'content/{blog,labo}/posts/*.md',
      check: (content: string): RuleHit[] => {
        const hits: RuleHit[] = [];
        const { data } = matter(content);
        const required = ['title', 'publishedAt', 'category', 'slug', 'description'];
        required.forEach(field => {
          if (!data[field]) {
            hits.push({ message: `必須フィールド「${field}」が見つかりません` });
          }
        });
        return hits;
      },
    },
    // BMD-002(強調記号禁止)、BMD-004(廃止フィールド検出)が続く
  ] satisfies FileRule[],
};
// scripts/flow/lint/engine.ts(抜粋)
const RUNNERS: Record<string, (options?: RunOptions) => Promise<RunResult>> = {
  'arch': runArch,
  'css': runCss,
  'template': runTemplate,
  'blog-metadata': runBlogMetadata,
  'markdown': runMarkdown,
  'comments': runComments,
  'spec-types': runSpecTypes,
};

差分は、検証ロジックを独自の実行基盤に乗せるか、既存のRUNNERSマップへの登録だけで済ませるかという一点にある。

② 設計判断

  • 【優先した価値】: RUNNERSへの登録だけで、起動時(w/build/deployのSTEPS)・commit(pre-commit)・push前の3つの品質ゲートすべてに自動で乗る。専用ツールを別途どこかのフックへ配線する手間が発生しない。
  • 【犠牲にした価値】: 出力フォーマットの自由度。共有エンジンが持つViolation型・printSummary/writeLogの形式に従う必要があり、ブログメタデータ特有の見せ方(ファイルごとにグループ化した独自レポート等)は共有エンジンの仕様に合わせて表現し直す必要がある。

③ 技術的負債

  • 【採用した案が抱える負債】: blog-metadataカテゴリが実装しているルールはBMD-001(必須フィールドの存在チェック)・BMD-002(強調記号禁止)・BMD-004(廃止フィールド検出)の3件のみで、いずれも「フィールドが存在するか」「特定の記法を含むか」という構文的なチェックにとどまる。記事のcategoryやtagsの値がapp/specs/blog/posts-spec.yamlで定義された許可リストに実在するかという値の妥当性チェックは、このリントには実装されていない。カテゴリ名を誤字(例:「ガイド」を別表記で書く)で保存しても、このリントは検出できない。限界が来る条件は「記事のカテゴリ名やタグ名がspecの許可リストから外れた瞬間」であり、その検出はレビュー時の目視に依存したままになっている。

④ 経営翻訳

新規の申請書チェック業務を立ち上げる際、専用の審査部署を新設する案と、既存の全社共通チェック窓口に審査項目を1つ追加する案を比較した。後者を選んだことで、新しい申請書も既存の窓口が回している「受付時・承認前・提出前」の3段階チェックにそのまま乗る。ただし今のところ追加した審査項目は「必要書類がすべて揃っているか」「禁止表現を使っていないか」の2点に限られており、「記載内容が社内で定めた正式な分類名と一致しているか」までは審査していない。分類名の表記ゆれは、審査を通過したあとの目視確認に委ねられたままになっている。