記述ルールとベストプラクティス — Lint統一とCI組み込み、まとめ

レビューのたびに「ここはcamelCaseかsnake_caseか」という指摘が繰り返されるのを見て、ルールを決めて機械的にチェックする仕組みに乗せない限り、この議論は無限に続くのだと痛感しました。最終回では、決めたルールを「人の記憶」ではなく「CIの合否」に落とし込むところまでをまとめます。

なぜ記述ルールが必要か

YAMLは書き方の自由度が高いフォーマットです。同じ内容でもインデント幅を2にするか4にするか、キー名を snake_case にするか camelCase にするか、複数の選択肢があります。これは裏を返せば、ルールを決めておかないと、ファイルごと・書いた人ごとにスタイルがバラバラになるということです。

スタイルのばらつきは、レビュー時の「本質的でない指摘」を増やし、差分（diff）を無駄に大きくし、新しくチームに入った人の学習コストを上げます。PART 02・PART 03で扱った「読める・動く」の次の段階として、「揃っている」を目指すのが本記事のテーマです。

命名規則 — キー名のスタイルを揃える

YAMLのキー名には言語仕様上の制約はほぼありません。だからこそ、プロジェクトごとに明示的なルールを決める必要があります。

スタイル	例	よく使われる場面
snake_case	`max_retry_count`	Python系ツール、Ansible、多くのOSS設定ファイル
camelCase	`maxRetryCount`	JavaScript/TypeScript系ツール、npm関連の設定
kebab-case	`max-retry-count`	GitHub Actionsの一部キー、CLIオプションに近い設定

💡 迷ったら「その設定を読み込む側の言語」に合わせる

独自の設定ファイルであれば、設定を読み込むアプリケーションの主言語の慣習（Pythonならsnake_case、JS/TSならcamelCase）に合わせるのが最も摩擦が少ない選択です。一方GitHub ActionsやKubernetesのようにフォーマットそのものが決まっている場合は、そのツールの慣習に従います。

⚠️ 1つのファイル内で混在させない

「ここはuserIdなのに、あそこはuser_name」のように混在すると、キー名を毎回思い出せず入力ミスの元になります。プロジェクト内では最低限、1つの設定ファイル・1つのスキーマの中では統一してください。

インデント幅の統一

PART 03で触れた通り、YAMLのインデント幅に仕様上の決まりはありません。実務では2スペースが最も広く使われていますが、重要なのは「何スペースか」より「プロジェクト内で統一されているか」です。

2スペース（推奨）

Kubernetes・GitHub Actions・Docker Composeなど主要ツールの標準。ネストが深くても横に広がりにくい。

4スペース

Pythonのコード規約（PEP 8）に慣れたチームで採用されることがある。ネストが深いと横に広がりやすい。

この記事のシリーズでも一貫して2スペースを使ってきました。PART 02で導入したyamllintの .yamllint 設定にある indentation.spaces の値を、チームで決めた幅に固定しておくことで、エディタや個人の癖に関わらず統一が保たれます。

yamllintルールのチーム標準化

決めたルールは、レビューコメントではなくyamllintの設定ファイルに落とし込みます。PART 02で紹介した .yamllint をベースに、チーム標準として拡張した例を示します。

YAML — チーム標準の .yamllint 設定例

extends: default

rules:
  indentation:
    spaces: 2
    indent-sequences: true

  line-length:
    max: 120
    level: warning

  truthy:
    allowed-values: ["true", "false"]
    check-keys: false

  comments:
    min-spaces-from-content: 1

  document-start:
    present: false   # 単一ドキュメントでは --- を必須にしない

  key-ordering: disable   # キーの並び順は強制しない

ignore: |
  vendor/
  node_modules/
  .venv/

方針	理由
命名規則自体はyamllintで強制しない	yamllintはキー名のスタイル（snake_case等）までは検査できないため、命名規則はドキュメント化とレビューで担保する
indentationは厳密に固定	機械的に検出・強制できる項目は、必ずLintに寄せる
truthyは true/false のみ許可	PART 03の「ノルウェーの問題」を未然に防ぐ

CI（GitHub Actions）への組み込み

yamllintを組み込んだGitHub Actions CIパイプラインの流れを示す図

図1: ローカルのエディタチェックに加えて、CIでも同じルールを機械的に強制する

エディタでの目視確認だけに頼ると、レビュアーが見落とせば崩れた設定がマージされてしまいます。yamllintをCIに組み込み、ルール違反があればPRをマージできないようにするのが最も確実です。

YAML — .github/workflows/yamllint.yml

name: YAML Lint

on:
  pull_request:
    paths:
      - "**/*.yml"
      - "**/*.yaml"

jobs:
  yamllint:
    runs-on: ubuntu-latest
    steps:
      - name: リポジトリをチェックアウト
        uses: actions/checkout@v4

      - name: Pythonのセットアップ
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: yamllintのインストール
        run: pip install yamllint

      - name: yamllintの実行
        run: yamllint -c .yamllint .

このワークフローは、*.yml / *.yaml を含むPull Requestが作成・更新されるたびに自動実行されます。yamllint の終了コードが 1（エラーあり）の場合、GitHub Actions上でジョブが失敗として扱われ、リポジトリの設定でこのチェックを必須化しておけばマージがブロックされます。

✅ ブランチ保護ルールと組み合わせる

GitHubリポジトリの Settings → Branches → Branch protection rules で「Require status checks to pass before merging」を有効にし、この yamllint ジョブを必須チェックに指定すると、ルール違反のあるYAMLがmainブランチに混入すること自体を防げます。

シリーズ全体のまとめ

全5回を通して、YAMLの特徴からツール導入、基本記法・応用記法、そしてチームでの運用ルールまでを解説してきました。

PART	内容
01	YAMLの特徴、用途、JSON/XMLとの比較
02	VS Code拡張機能とyamllintによる構文チェック環境構築
03	マッピング・シーケンス・スカラー値とインデントルール
04	アンカー・参照・複数ドキュメント・フロースタイル
05（本記事）	命名規則・Lintルールの統一とCI組み込み

💡 最初の一歩は「.yamllintを1つ置くこと」

ルールをすべて決めきってから始める必要はありません。まずはPART 02の設定例を1つ置き、CIに組み込むところから始めれば、少なくとも「壊れたYAMLがマージされる」事故は防げます。命名規則などのチーム固有のルールは、運用しながら少しずつ育てていけば十分です。

読んでいただきありがとうございました。ここで扱いきれなかったJSON SchemaによるYAML検証の詳細や、Kubernetes固有のマニフェスト設計などは、別シリーズで改めて扱う予定です。

PART 05 — 記述ルールとベストプラクティス
Lintルールの統一とCI組み込み、シリーズまとめ