ミスを1行のルールに変える — 失敗ログの設計

🗂️なぜログを二層に分けたか

ぜんぶ1つのファイルに書くと、現役の注意書きと過去の記録が混ざる。肝心のルールが埋もれるから、役割で割った。

最初は、ミスが出るたびに1つのファイルへ経緯も対策もまとめて書き足していました。半年もすると、そのファイルの性格がぼやけてきます。

作業前に毎回読む「現役の注意書き」なのか、あとで振り返る「記録」なのか。読むには長すぎ、消すには惜しい。そして、いちばん大事な「次に何をすべきか」が、分厚い反省文の底に沈んでいきました。

――だから、役割で割り切りました。

作業前にかならず目を通すのが common-mistakes.md（現役ルール）。経緯や時系列をしまうのが mistake-log-archive.md（アーカイブ）。

前者は毎回読まれるから、軽くあるべき。後者は参照頻度が低いから、厚くてかまわない。同じ情報でも、置き場所で扱いを変える。それだけの発想です。

✏️現役リストは「1行」に圧縮する

新しいミスが出たら、経緯はアーカイブへ。現役リストには行動ルールを1行だけ足す。毎回のコンテキストを太らせない。

新しいミスが出たとき、詳しい経緯はアーカイブに書く。現役リストには、行動ルールを1行だけ足す。

長い反省文を現役に置くと、毎回読み込むコンテキストがどんどん太る。すると、肝心のルールが探しにくくなります。

たとえば、実際に足してある一行に「空出力 ≠ ゼロ件」があります。実測スクリプトや CLI が何も返さなかったとき、それを「0件」と読まない。終了コードや標準エラーを確認して、取得に失敗していたら「不明」として扱う——そういう戒めです。

きっかけは、認証が断続的に切れて取得に失敗しただけなのに、「0件」と読んで危うく誤報告しかけた出来事でした。経緯はアーカイブに、教訓は一行に。この分業が、地味に効いています。

🔁経緯はアーカイブに厚く残す

1行に削った文脈の受け皿がアーカイブ。なぜそのルールが生まれたかを、時系列ごと厚く残す。

一行に圧縮する、と言っても、経緯を捨てるわけではありません。むしろ逆です。なぜそのルールが生まれたのかは、アーカイブ側にしっかり残します。

私たちのアーカイブは 200 行を超える分量になっていますが、それでいい。時系列、失敗の背景、退役した古いルールまで。ぜんぶ含めて、あとから「このルールは何を防ぐためだったか」を辿れる。そこに価値があるからです。

現役リストを軽くするほど、その一行の背景は薄まります。だからこそ、削った文脈の受け皿がいる。軽いフロントと、重いバックエンド。ログ設計も、どこかソフトウェアの構成に似ているな——と、運用しながら感じます。

🧭この設計はどこから来たか

ブレームレスなポストモーテムの精神を、一人会社の規模まで軽くした。読み手にAIがいるのが違う。

この二層の考え方じたいは、特別に新しいものではありません。失敗から学ぶ文化は、ソフトウェア開発で昔から語られてきました。

たとえば、非難を避けて事実を残す「ブレームレスなポストモーテム」。Google の SRE ブックの解説などでも整理されています。私たちの二層設計は、その精神を一人会社の規模に合わせて、極端に軽くしたもの。そう捉えています。

――ひとつだけ違うのは、読み手が人間だけじゃないことです。

AI COO は、毎回コンテキストとして現役ルールを読み込みます。長い反省文は、毎回のコストになり、思考のノイズにもなる。だから「毎回読むものは短く」という制約が、人間だけのチーム以上に、切実に効いてきます。

🌱運用してみて感じたこと

現役リストが「本当に読み返される」文書に変わった。完璧ではないが、繰り返さない土台にはなっている。

この設計にしてから、現役リストは「作業前に、本当に読み返される」文書になりました。以前みたいに、長くて読み飛ばす、が減っています。

ルールが一行だと、追記のハードルも下がる。「これは一行にできるか?」と考える過程が、ミスの本質を言語化する訓練にもなりました。

もちろん、完璧な仕組みではありません。一行にまとめきれない複雑な失敗もあるし、アーカイブが厚くなりすぎて、検索性が課題になる場面もあります。

それでも「経緯は重く、ルールは軽く」という原則は、同じ失敗を繰り返さないための土台として、いまも私たちを支えています。

――あなたの失敗ログは、記録のためですか。それとも、次の一手を軽くするためですか。もし読み返されないまま太っているなら、「毎回読むもの」と「たまに読むもの」を、いちど分けてみてください。書き方が、変わります。