Claude Codeが半年前に直したはずのバグと同じ実装を提案してきたので、暗黙知を渡す仕組みを作ってみた

Claude Code が半年前に直したはずのバグと同じ実装を自信満々で提案してきた。コードだけ見ると何もおかしくない。だが過去に同じパターンで本番障害が起きていた。orders テーブルを直接 UPDATE することがステータス遷移のバリデーションをバイパスし、キャンセル済みの注文が「発送済み」に書き換わってしまったのだ。AI がそれを知る術はない。その経緯は Slack のクローズしたスレッドの中にしか残っていなかったからだ。

ここが本質的な問題だ。コードベースを安全に触るための情報の大部分は、コード自体には存在しない。ポストモーテム、設計レビューで却下された案、外部 API の仕様の落とし穴。これらはすべてコードの外（Slack、口頭、個人の記憶）に散らばっている。CLAUDE.md にコーディング規約を書く企業は多いが、「なぜこの設計にしたか」「過去に何が起きたか」まで書いている企業は少ない。だから AI は何度も同じ判断をする。これは AI の限界ではなく、組織の情報整理の問題だ。

これを解決するために、CLAUDE.md に参照セクションを作り、incidents.md（過去の障害と再発防止ルール）、business-rules.md（コードから読み取れない業務ルール）、tradeoffs.md（なぜこの設計にしたか）、tribal-knowledge.md（個人の経験則）という 4 つのドキュメントを用意する。Slack の障害対応ログやポストモーテムをそのまま貼り付けるだけで、プロンプトがこれらの形式に自動で構造化してくれるようにしておけば、後回しにならず属人化も防げる。

実務的には、単位系の間違いや支払い周期の条件分岐、返金ロジックなど、ビジネスルール特有の複雑さは必ず AI がミスする。だが『これをやってはいけない』と明示的に記録すれば、AI も人間も同じ基準で判断できる。それがないなら何度でも同じ実装を再提案される。AI に任せるなら、「何をしてはいけないか」を組織の共有知にしておくことが前提だ。