🏗️

Claude Codeで開発の『ゴミ』を溜めない — ファイルと機能の整合性を自動検証する仕組み

に公開
AI
自動化
設計
SRE
Claude Code
tech

Claude Code の CLAUDE.md を設計して2週間。きれいに整理したはずの設定が、また散らかり始めていた。

「場当たりルールを設計された憲法にリビルドした」。そう思っていた。でも設計しただけでは維持できないことに気づいた。今回の改修では「自律的に進化する仕組み」を目指した。

この記事では、何が問題だったか、なぜ変えたか、具体的にどう実装したかを書く。

ゴミが溜まった原因 — 散らかった部屋にルンバは置けない

前回の構成では「5層アーキテクチャ」「トークン経済学」「サービス設計原則」を定義した。ルールとしては機能した。

問題はルールの外側にあった。

  • 試行錯誤で作った一回限りのスクリプトが9本放置されていた
  • 廃止した機能のフォルダ・ファイルが残り続けていた
  • 3つのリポジトリに同じ lib.sh が微妙に違う形でコピーされていた
  • settings.local.json にセキュリティリスクのある権限が残っていた

CLAUDE.md にはルールを定義した。でもどの機能がどのファイルに紐づいているかを管理していなかった。機能を廃止してもゴミが残る。ゴミが溜まるとコンテキストが汚染される。AIが「これはまだ使われているのか？」と判断できなくなる。

整理されていない部屋にルンバを置いても、障害物を避けるだけで掃除にならない。

追加した設計原則 — 自律動作を前提にした4つ

この問題を踏まえ、4つの設計原則を追加した。どれも「AIが自律的に動く前提」で必要になったルールだ。人間がセッションに張り付いていたころは暗黙のルールで済んでいた。cronで夜間にも動くようになってから、明文化が必要になった。

コンテキスト分離原則
同じデータでも関心事（収集・分析・通知）が異なれば別サービスにする。頻度・コスト・実行層が異なる処理を1つのスクリプトに混ぜない。

本番保護原則
cron・外部API・公開リポジトリへの変更は必ずドライランで先行確認する。--dry-run でリハーサルできないスクリプトは本番投入しない。ドライランなしのスクリプトが本番cronに残っていたことで追加した原則だ。

著作権原則
生成コンテンツはオリジナルであること。外部コンテンツの逐語複製は禁止。ファクト情報は利用可能だが、公式の説明文をそのまま使わない。

情報鮮度基準
CVE（CVSS 7+、重大・高）は2週間、バージョン情報は1ヶ月、トレンドは3ヶ月。超過した情報は再確認する。

architecture.md — 機能とアーティファクトの対応表

最初にやったのは、各リポジトリに architecture.md を作ることだった。

## 機能一覧

### デプロイ前レビュー
- **ステータス**: ACTIVE
- **dirs**: scripts/, reports/
- **scripts**: scripts/pre-deploy-check.sh
- **commands**: .claude/commands/review.md
- **cron**: `0 8 * * 1-5 pre-deploy-check.sh`

### Slackアラート通知
- **ステータス**: DISCONTINUED
- **dirs**: scripts/alerts/

ルールは3つだけ:

  1. 全ての機能に ACTIVE / NOT STARTED / DISCONTINUED のステータスを付ける
  2. 機能に紐づくファイル（dirs, scripts, commands, cron）を全て列挙する
  3. 機能を廃止するときは、紐づく全アーティファクトを同一コミットで削除する

3番目が一番重要だ。「機能は消えたのに設定ファイルだけ残っている」状態を構造的に防ぐ。

health-check.py がこの対応表と実際のファイルの整合性を自動検証する。対応表を更新し忘れても検出できる。

情報収集パイプライン — 収集と判断を混ぜない

今回新設したのが、技術フィード収集とセキュリティトリアージのcronジョブだ。

毎日6時: daily-tech-feeds.sh（L1: 収集のみ）
  → fetch-tech-feeds.py が RSS/Atom を取得
  → tech-feeds-latest.json に保存
  → weekly-review が分析（L3）

毎日7時: daily-security-triage.sh（L1→L3: 収集＋判断）
  → fetch-tech-feeds.py が GitHub Advisory (critical) を取得
  → Sonnet がトリアージ（urgency/relevant の判断）
  → Slack に通知

ポイントはコンテキスト分離だ。

技術フィードとセキュリティは同じ「外部情報の収集」でも、頻度・コスト・判断の重みが全く違う。技術フィードは週次で人間が眺めれば十分。セキュリティは毎日AIがトリアージして、HIGHがあれば即通知する必要がある。

一つのスクリプトにまとめると、片方の変更がもう片方に影響する。分離すると影響範囲が絞られる。実際このモデル変更は daily-security-triage.sh の1行で完結した。

L5 自律権限 — AIが自分でルールを更新する

以前はルールの追加・修正は全て人間の確認が必要だった。今回は一部の操作にstanding permission（事前承認）を与えた。

## L5 自律権限 — AIへの事前承認

ユーザー確認なしに行動できる:
- coding-standards.md / known-failures.md へのルール追記・修正
- health-check.py へのチェック項目追加
- メモリの整理（重複削除・陳腐化更新）

ユーザー確認必須:
- CLAUDE.mdの変更
- ルールの削除・緩和
- スクリプトの新規作成・既存ロジックの変更
- crontab の変更
- 外部サービスへの通信

「追記はOK、削除はNG」という非対称性がポイントだ。ルールを厳しくする方向は安全だが、緩める方向はリスクがある。新しい失敗パターンを known-failures.md に追記するのはAIだけで判断できるが、「このルールはもう要らない」と判断するのは人間の仕事だ。

この権限があることで、AIがセッション中に気づいた改善点をその場で反映できる。「次のセッションで対応しよう」と先送りにならない。権限設計の詳細（何をAIに任せ、何を人間が判断するか）は別記事で扱う予定だ。

移行手順 — 再現可能な形で

今回の改修は1セッションで完了した。手順を残しておく。

掃除フェーズ

  1. 対応表を作る: 各リポジトリで architecture.md を作成。全機能とそのステータスを列挙する
  2. 廃止機能のゴミを一掃: 対応表を見ながら、廃止された機能のファイルを削除する
  3. 重複を統合: 複数リポジトリに分散していた lib.sh を1箇所に集約する

維持フェーズ

  1. ルール体系を整備: CLAUDE.md の欠落を補完し、メモリの重複を整理する
  2. 自動検証を入れる: health-check.py を拡張して、対応表との整合性チェックを追加する
  3. 自律権限を付与: 安全な範囲でAIが自己改善できるstanding permissionを定義する

掃除だけやっても次のセッションでまた散らかる。維持の仕組みまで入れて初めて完成する。

設定は書いて終わりではない

CLAUDE.md を再設計したとき、「これで完成した」と思っていた。それは2週間で散らかった。

学んだのは、設定は運用するものだということだ。コードと同じで、書いた瞬間から腐り始める。health-check（検知）・L5自律権限（修復）・architecture.md（蓄積防止）の3点セットが要る。

設定を「設計」するだけでなく「運用」する。SREの考え方がそのまま当てはまる領域だった。

リポジトリは公開している。構成を見たい場合は参考にしてほしい。

https://github.com/ojt-sre/claude-config

Discussion