「意図」のない成果物は何を語るのか――判断不能な組織への入り口

この記事が語ること

「意図」を残さない現場では何が起こるのか。
答えは「判断不能に陥る」。
判断不能を乗り越え、前進できる現場を作るための考え方をまとめる。

手が出せそうで、出せなかった

あるとき、深いロジックの不可解な場所に、グローバルな値定義を見つけた。
参照箇所を調べると、確かに限定的に何かに使われてはいるらしい。
これなら、現状に合わせて配置を変更してリファクタしても、不都合はなさそうだ。
既存の回帰テストも壊れなかった。

しかし、「何らかの意図を持って配置されている」ように見える理由は、コードからは皆目見当がつかなかった。

だから徹底的に調べた。
時間の許す限り、コミットログを遡り、経緯を追った。
それでも、確証は得られなかった。

なぜこの位置に定義が入ったのか。
何を守るためのものだったのか。

特にECという複雑に入り組んだドメインでは、「どこかで使われている可能性」「何かを引き起こす可能性」を完全に否定することが難しいこともあった。

結局、そのコードには手を出さなかった。
判断を保留したのだ。
この結論は間違いではなかったはずだ。

ただ、変えられそうで、変えられなかった。
判断できなかったことが、悔しかった。

なぜこんなことになるのか？

コードは「どう動くか」を表す。
しかし、ときに実務では「なぜそうしたか」を知らなければならない時がある。

• 事故対応
• 例外対応
• 時限暫定対応
• 歴史的経緯

こうした“意図”は、基本的に成果物には残らない。

「何のために？」「なぜ？」
が頭に浮かぶ瞬間、判断不能が発生する。

ここで言う"意図"とは「なぜそうしたか」ではなく、その判断に用いた評価基準であり、
"判断不能"とは、安全かどうかを根拠付きで説明できない状態を指す。

意図が空白となった地帯は、事故の遠因となり、遅延の原因となり、プロダクトの寿命を削る。

だからこそ、意図を残す必要があるのだ。

記憶依存は、強烈な危険信号

「こうなった理由、思い出せる？」

この言葉が出た時点でアウト判定を下してもいい。

人の記憶に頼る判断。
当事者不在で再現不能。

記憶に依存した瞬間、安全性は個人の脳に委ねられる。
責任が散らばり、判断が宙に浮く。
曖昧な個人の記憶に基づいて組織の意思決定が行われる。

そこにあった意図を評価できないと、安全側に倒す動機が強まり、それが常態化する。
安全に倒し続けた結果、技術的負債が凍結される。
それが正しい判断だったのか、根拠を持った説明が不可能になる。
結果、組織は硬直する。

まして、意思を持たず、コードしか見られない存在ならばどうか？
AIをもってしても、確証を伴った解釈は不可能な領域なのだ。

意図を残すという仕事

普通に仕事をしていたら、そこにあった意図は流れて消える。
成果物は残っても、意図は霧散する。

成果物と意図は、本質的にレイヤーが異なるものだ。
成果物は結果であり、意図は判断の文脈である。

では、どうやって、他者に伝わるように意図を残すのか。

意図を成果物の近くに配置するしかない。

意図は、性質によって"適切な距離"が異なる。

• 最高優先度
  • 事故対応
  • 特殊対応
  • 時限暫定対応

これらは少なくとも、コードコメントに置くべきだ。
迷わず埋め込んで構わない。
これらは、知らなかったら、あるいは読み落としたら、即事故につながる。

• 中優先度
  • リファクタ余地がある
  • 事情はあるが即問題にはならない

これらはコミットメッセージやレビューコメントに付加すればよいだろう。
あとからでも当該箇所の履歴を簡単に遡れることが重要だ。

• 低優先度
  • 技術選定の理由
  • いずれ解決したほうがよい事項
  • チーム内の共有情報

これらはIssueやSlack、その他ドキュメントが適切だろう。

重要なことは、意図は全て同じ場所に置けばいいというわけではない、ということ。
例えば、熱量の少ないこともいちいちコードコメントに書き込んでいたら、書き手も読み手も疲弊する。
性質に応じて"距離"を選ぶのが最善だ。

簡単な問いに直すなら、
「それ、どれくらい大事なの？」
と自分に聞いてみることだ。

意図というレイヤーを、成果物に並べる

このように、成果物と適切な距離感で意図を保存するスキルのことを、筆者は
意図アーカイブと呼んでいる。

これは、未来に検索され、参照され、再利用されることを前提とした保存である。

まずは、完璧な保存を目指さなくともよい。

• 一行でいい
• 走り書きでいい
• 参照先の指示でいい

示す情報量は少なくても構わない。
ただ、どういった意図を残すのかはよく考えなければならない。

• 制約の評価軸を残せ
• 何を恐れているのかを書け
• 守ろうとしているものを示せ

このスキルは、特別なことは求めていない。
未来の誰かのために、判断の再現性を置いておくだけの技術だ。
そのときの、ありのままを残しておけばいい。

実務原則：まずはどこでもいいから残せ

理想は、性質に応じて配置する距離を最適化すること。
しかし、実務はそんなに綺麗ではない。

• 時間がない
• 仕様が揺れる
• 緊急対応が入る
• そもそも整理する余裕がない

だからこそ、実務ではこうなる。

"意図が霧散する前に、どこでもいいから残せ"

距離の思想は“理想”ではなく“方向性”。
最初から完璧に分類する必要はない。

• Slackでもいい
• Issueでもいい
• コミットコメントでもいい
• コードコメントに殴り書きでもいい

意図がゼロより、残し方が荒いほうがまだマシ。
そして、後から整備すればいい。
必要に応じて説明を体系化をしていけばいいのだ。

未来の誰かへ判断材料を残す

「何のために？」「なぜ？」

ここまで示してきたスキルは、未来の誰かを、こういった判断不能から救うためのものである。

また、誰かに意図を説明できるということは、根拠を持ってその設計を作り上げた証左でもある。
説明できない意図は、それ自体が危うさを示しているのだ。

あなたの現場には、「意図の分からないもの」がどれだけ存在しているだろうか？
ぜひ見直してみてほしい。