diff --git a/.coderabbit.yaml b/.coderabbit.yaml
index 1990fd32..5dc465a5 100644
--- a/.coderabbit.yaml
+++ b/.coderabbit.yaml
@@ -1,10 +1,16 @@
+# CodeRabbit（PR に付く AI のレビュー）の設定。#273 で入れた。
 language: ja-JP
 reviews:
+  # 指摘の粒度を厳しすぎない程度に抑える。
   profile: chill
   auto_review:
     enabled: true
   tools:
     golangci-lint:
+      # CodeRabbit は golangci-lint をリポジトリの直下から動かし、作業ディレクトリを指定できない。
+      # go.mod が api/ にしか無いため、設定を渡しても失敗することがある（#373）。
+      # Go の lint は .github/workflows/go-lint.yml が本命なので、go-lint が通っていれば、ここの失敗は直さなくてよい。
       config_file: "api/.golangci.yml"
 chat:
+  # CodeRabbit のスレッドに返信すると、CodeRabbit が自動で返信する。返信せずに Resolve するだけなら返信は来ない。
   auto_reply: true
diff --git a/.github/workflows/go-lint.yml b/.github/workflows/go-lint.yml
index e74f2897..70d913be 100644
--- a/.github/workflows/go-lint.yml
+++ b/.github/workflows/go-lint.yml
@@ -1,3 +1,5 @@
+# Go（api/）の lint。golangci-lint の設定は api/.golangci.yml。
+# Go の lint はこの CI が本命。CodeRabbit も golangci-lint を回すが、補助として扱う（.coderabbit.yaml のコメント）。
 name: go-lint
 
 on:
@@ -24,5 +26,8 @@ jobs:
         uses: golangci/golangci-lint-action@ba0d7d2ec06a0ea1cb5fa41b2e4a3ab91d21278a # v9.3.0
         with:
           version: v2.12
+          # go.mod は api/ にしか無いので、api/ で動かす。
           working-directory: api
+          # PR が新しく持ち込んだ違反だけで落とす。導入したとき既存の違反が 74 件あり、全部で落とすと
+          # どの PR も通らなくなるため、段階的に厳しくする形にした（#375）。
           only-new-issues: true
diff --git a/api/.golangci.yml b/api/.golangci.yml
index f9dc2366..2d539a15 100644
--- a/api/.golangci.yml
+++ b/api/.golangci.yml
@@ -2,6 +2,13 @@ version: "2"
 
 linters:
   enable:
+    # gosec は、SeeFT の連結 SQL を SQL インジェクションとして拾えない。経路は2つある。
+    # - abstract.Crud 経由：SQL を実行する関数を gosec が決め打ちで持っていて、設定から足せない（gosec v2.26.1 で確認）
+    # - DB() からのメソッドチェーン（bureauRepository.FindByBureau など）：gosec だけをかけても検出されなかった
+    #   （2026-10-01 に golangci-lint v2.12.2 で、repository の連結 45 行に対して 0 件）
+    # 0 件でも、連結 SQL が無い証明にはならない。
+    # SQL の守りは AGENTS.md のプレースホルダの規約とレビューで、根本対応は #266。
+    # それでも SSRF・弱い暗号・ファイルパスなどのルールは役に立つので、有効のままにする。
     - gosec
     - revive
   settings:
@@ -9,10 +16,16 @@ linters:
       severity: warning
     gosec: {}
     govet:
+      # govet は既定で有効なので、linters.enable には書かない。ここでは既定で回らない analyzer を足す。
+      # unusedwrite は誤検知が無く、実際に使われていない書き込みを拾ったので足した（#430/#431）。
+      # shadow（err の再宣言が Go の定石と衝突して誤検知を含む）と fieldalignment（この規模では実利が無い）は見送った。
+      # 見直すときは、件数を測り直してから決める。
       enable:
         - unusedwrite
 
 issues:
+  # 既定の上限（同じ指摘 3 件、1 linter 50 件）だと件数が隠れ、片付けのときに件数を読み違えた（#371）。
+  # 0 は上限なし。
   max-same-issues: 0
   max-issues-per-linter: 0