コードを書く前に、仕様を自分の言葉で箇条書きにしてもらう

自分のチームでは、タスクに着手する前に「何を作るか」を箇条書きで説明してもらうステップを入れている。言葉で説明できてから、コードを書き始める。

これだけのことだが、仕様の曖昧さが実装の前に見つかるようになった。なぜ効くのか、どう進めているかを書く。

背景：「なんかうまくいきません」で止まる

実装の途中で手が止まり、相談が来る。そのとき「どこで詰まっているか」ではなく「なんかうまくいきません」という形で来ることがあった。

話を聞いていくと、ほとんどの場合、何を作るかが整理されないまま実装に入っていた。コードのイメージが先に浮かんで手を動かし始め、途中で「このデータはどこから来るのか」「バリデーションはどこでやるのか」に突き当たる。そこで初めて「何を作るか」に戻ることになる。

これは一般に、経験の長さに関係なく起こりうることだと思う。問題は個人の力量というより、着手の手順にあると考えた。

試行錯誤の末に定着したのが、着手前に何を作るかを箇条書きで説明してもらうステップだ。

実際のやりとりは、たとえば次のようになる。来院記録を登録する機能を追加するタスクの例だ。

渡す側「次はこれをお願いします。来院記録を登録する機能の追加です」

担当者「わかりました」

渡す側「コードを書く前に、何を作るかを箇条書きで説明してもらえますか」

担当者「対象者のIDと来院日を受け取るAPIを作って、DBに保存します。バリデーションは、IDが存在するかどうかと、来院日が未来の日付かどうか……」

渡す側「来院日が未来の日付、という制約はどこに書いてありましたか」

担当者「仕様書には……書いていないかもしれません」

渡す側「では、そこは今のうちに確認しておきましょう」

この一往復で、仕様にない制約が実装の前に表に出た。この制約が正しいかどうかは、この時点では分からない。分かったのは「仕様書に書かれていないことを前提にしようとしていた」という事実で、それが確認すべき項目になる。コードを30分書いた後で気づくより、ずっと安く直せる。

例のやりとりを型にすると、説明してもらうのは次の4点になる。

1. 入力：何を受け取るか（項目と形式）
2. 処理：受け取ったものをどうするか（保存先、更新する対象）
3. 制約：どんなバリデーションをかけるか
4. 出どころ：それぞれが仕様のどこに書いてあるか

効くのは4つ目だ。1〜3は頭の中のイメージをそのまま話せば埋まるが、4は仕様に戻らないと答えられない。「どこに書いてありましたか」と聞くのは、間違いを指摘するためではなく、書いてあることと自分で補ったことを分けるためだ。

聞く側は、説明の途中で正解を言わないほうがよい。こちらが先に補ってしまうと、曖昧な箇所が表に出ないまま実装に入ってしまう。

このステップを入れると、詰まる場所が変わる。コードの中で詰まるのではなく、言葉にする段階で詰まるようになる。

言葉の段階で詰まったときは、原因が「仕様が足りない」か「仕様を読み違えている」のどちらかに絞られるので、確認する相手も内容もはっきりしている。コードの中で詰まると、実装の問題なのか仕様の問題なのかの切り分けから始めることになる。

もう一つ、相談の質が変わる。何を作るかを一度言葉にしていると、詰まったときにも「この項目の扱いが決まっていない」という形で話しやすくなる。要件を整理して話すことは、コーディングより手前にある基礎だと考えている。

仕様の誤解は、一般的なWebアプリでもバグになる。ただ、自分が担当しているのは医療系の、規制のある業界の業務システムで、影響の性質が少し違う。

この種のシステムでは、データの正確性と追跡可能性が求められる。「想定外のデータが入った」「ステータスが意図しないタイミングで変わった」は、単なる不具合ではなく、データの完全性への影響として扱わなければならない場面がある。

動けばよい、では済まない。だから仕様の曖昧さは、実装の前に潰しておく意味が大きい。

このステップを入れても、詰まりがすべて消えるわけではない。言葉で説明できたつもりでも、実装してみて初めて分かることは残る。着手前の説明は、あくまで安く見つけられる問題を先に見つけるためのものだ。

また、箇条書きは最初の一歩にすぎない。次の段階として考えているのは次の順番だ。

実装だけでなく設計もできるようになることを目指していて、箇条書きはその一番手前にある。チームとしてはまだ途中の段階だ。

関連記事: