個人開発で失敗を記録する六項目。却下と障害から残した形式

書く項目は六つに決めています。増やすと書かなくなり、減らすと数か月後に読めなくなりました。

下の六つで一番効いたのは、五番目の採用しなかった案です。直した内容だけを残すと、あとから読んだ自分が「もっと良い方法があるのでは」と考え直します。そのとき、一度検討して落とした案をもう一度検討することになります。

六項目のうち、最後の「自動で気づく方法」だけは埋まらないことがあります。機械で判定できない失敗もあるからです。そのときは空欄にせず、判定できない理由を書いておきます。書かないと、次に読んだ自分が「なぜ検査にしていないのか」から調べ直します。

• いつ、どの環境で起きたか。
• 利用者に何が見えたか。何も見えなかった場合は、それを書く。
• 影響した範囲。分かっていない範囲も書く。
• 確認できた直接の原因。
• 採用した修正と、採用しなかった案とその理由。
• 次に同じことが起きたとき、自動で気づく方法。

記録がいちばん役に立たなくなる書き方は、事実と推測を同じ文に混ぜることです。「権限の設定が原因で一覧が空になっていた」と書くと、空になっていたのは事実なのか、原因が権限なのはどこまで確かめたのかが分かりません。

分けて書くと、数か月後に読んだときの扱いが変わります。事実はそのまま使えます。推測は、まだ確かめていない仮説として読めます。混ぜてしまうと、全部が確かめた事実として読まれます。

分けるコツは、一文に一種類しか入れないことでした。事実の文、推測の文、判断の文を別の行にします。同じ文に入れると、読み返すときにどこまでが確認済みか切り分けられません。

下の表の四行目にある「見送り」は、あとから足した行です。最初は事実・推測・判断・対策の四つで書いていましたが、落とした案の理由を書く場所がないことに気づきました。判断の欄に混ぜると、選んだ理由と落とした理由が同じ行に入ってしまいます。

六項目を埋めても、確かめきれない部分は残ります。そのとき空欄にせず、確かめていないと書くのが一番効きました。

一度、ある確認項目を閉じるときに「ストアの公開されている情報には出ないので、管理画面でしか確かめられない」と添えて残しました。閉じた根拠が自分の確認ではないことを、あとから読んで分かるようにするためです。書かないでおくと、数か月後の自分が「確かめた」と読みます。そこから先の判断が全部ずれます。

同じ理由で、やらなかったことも二つに分けて残しています。測ったうえで見送ったのか、そもそも見ていないのか。結果としてはどちらも「やっていない」ですが、次に判断するときにはまったく違う情報です。前者は理由を読んで再検討できます。後者は、まず見るところから始まります。

⚠️ 確認する側のコードが間違っていることもあります。私は一度、利用者が自分で決めたかどうかを調べるつもりの判定が、部品側が登録した既定値まで拾う書き方になっていて、切るべき場面で切らない結果を返していました。このときは、検査そのものを記録の対象にしました。

この「確かめていない」を書く習慣は、失敗の記録以外にも効きました。調べものの結果、外部のサービスの仕様、規約の解釈。自分の確認で閉じたのか、読んだだけで閉じたのかが区別できると、あとから疑う場所が絞れます。

記録を別の文書にまとめただけだと、整理した人が制約に気づかずに消します。その人は自分なので、悪気もありません。読んで意味が分からない一行は、消されます。

だから、理由へたどれる手がかりを変更する場所へ置いています。短いコメント、テストの名前、あるいは禁止されている語を機械が読める配列にしてしまうこと。

実際にやっているのは最後の形です。あるアプリのLPには使ってはいけない語があります。最初は説明の文章としてだけ書いてありましたが、守るかどうかが人まかせでした。いまは配列にしてあり、入るとビルドが落ちます。読まなくても効きます。

この置き方には限界もあります。機械で判定できないものは、文章のまま置くしかありません。そのときは、判定できない理由も一緒に書いておきます。そうしないと、次に読んだ自分が「なぜ検査にしていないのか」から調べ直します。

記録の置き場所を決める考え方はひとりで3つのアプリを作る。仕様を「頭の中」に置かないためにやっていることにまとめました。

置き場所を決めるときに一度間違えたのは、同じ内容を二か所に書いてしまったことです。説明の文章とコード内のコメントに同じ制約を書いて、片方だけ直しました。いまは、どちらかを正本と決めて、もう一方からは参照するだけにしています。

もう一つ、置き場所として使えるのがテストの名前です。何を守りたいのかを名前に書いておくと、落ちたときに理由が一緒に出ます。コメントは読まれないことがありますが、落ちた検査の名前は必ず読まれます。

起きたことと判断を整理すると、そのまま読み物になります。私は却下された記録と、本番を止めた記録を公開しています。

一つは、ストアの規約でアプリのコンセプトごと却下された件です。直した箇所ではなく、アプリが何であるかの説明を変えた記録になりました。App Storeに「似たアプリはもう十分ある」と言われて、アプリの主語を変えたに書いています。

もう一つは、安全のための設定を強くしたつもりが、本番の読み取りを止めた件です。セキュリティを強くしようとして、本番を止めた。RLSの見落としに残しました。この二つは、原因の種類がまったく違います。前者は説明の問題、後者は設定の問題でした。

書けない範囲もはっきりしています。利用者の個人情報、安全上の詳しい手順、そしてまだ直っていない不具合の再現方法。この三つは記録には残しますが、公開する記事には書きません。

⚠️ 恥ずかしさを理由に書かないのはやめました。私が公開して効いたのは、うまくいった話よりも、間違えて直した話です。同じところで詰まっている人が探している言葉は、成功のほうには入っていません。

公開して分かったのは、書いた本人が一番読み返すということでした。他の人に向けて整理した文章は、自分が読み返すときにも読めます。手元のメモは、数か月後の自分には読めませんでした。

個人開発で失敗を記録する意味はありますか？

一人だからこそ効きます。将来その制約を消すのは自分です。理由が分からない一行は消されます。数か月後の自分は、いまの自分とは別人だと思って書いておくのが一番早かったです。

記録が続きません。どう書けば続きますか？

項目を増やさないことです。私は六項目に固定しています。増やすと書かなくなりました。書く量ではなく、書く場所を決めておくほうが続きます。

原因が分からないまま直ってしまった場合はどうしますか？

分からなかったと書いて残します。空欄にすると、あとから「確かめた」と読まれます。原因が分からないという情報自体が、次に同じ症状が出たときの手がかりになります。

採用しなかった案まで書く必要がありますか？

六項目でいちばん効いた項目です。これが無いと、あとから読んだ自分が一度落とした案をもう一度検討します。落とした理由を一行残せば、その時間が要らなくなります。

失敗の記録はどこに置けばいいですか？

変更する場所からたどれる位置です。別の文書にまとめただけだと、整理した人が制約に気づかず消します。可能なら機械が読める形にします。私は禁止語を配列にして、入るとビルドが落ちるようにしました。

失敗を公開するのは不利になりませんか？

私は公開しています。効いたのは、うまくいった話よりも間違えて直した話でした。同じところで詰まっている人が探している言葉は、成功のほうには入っていません。ただし、直っていない不具合の再現方法は書きません。

審査に落ちた記録は、次に活かせますか？

落ちた理由の種類によります。私の場合、指摘されたのは実装ではなくアプリが何であるかの説明でした。チェックリストで防げる種類ではなかったので、記録に残したのは手順ではなく判断の変え方です。

利用者が来なかったことも失敗として記録しますか？

しています。反応が無いのは症状が見えないので、記録しないと流れます。公開して九日間利用者が来なかったとき、私が残したのは何を調べてどう考え直したかでした。そこから次の判断が変わりました。

記録した内容を、あとから探せるようにするコツはありますか？

症状の言葉で探せるようにしておくことです。原因の名前で見出しを付けると、次に同じ症状が出たときに探せません。困っている側は原因を知らないので、見えたことのほうで引きます。

この記事では、失敗を減らす方法を書いていません。減らす話と、起きたあとに次へ渡す話は別のことだと考えています。前者は公開前の確認の話になるのでアプリ公開前チェックリスト。全部通したのに問題が出た六つに分けました。

もう一つ書いていないのは、記録に使う道具です。私は文書ファイルとコード内のコメント、それにビルドで落ちる検査を使い分けていますが、これは一人で、同じリポジトリだけを触っているからできる形です。人が増えたときに同じやり方で足りるかは分かりません。