はじめに
「仕様は口で言ったから大丈夫！」
え、まだ仕様を口頭だけで伝えてるんですか？口頭伝達チームはドキュメント化チームより手戻りが平均2.3倍多いです
この記事で解決すること
動画「【コミュ】仕様を口頭で伝えたら全然違うものができた」の補足記事です。
動画では時間の都合で触れられなかった詳細を解説します。
問題：なぜこれが危険なのか
え、まだ仕様を口頭だけで伝えてるんですか？口頭伝達チームはドキュメント化チームより手戻りが平均2.3倍多いです
解決策：明日から使えるベストプラクティス
要件をNotionやConfluenceに箇条書きで文書化し、認識合わせをしてから着手する
以下は、YouTubeや社内勉強会でそのまま使える構成の具体例です。
問題：なぜこれが危険なのか
え、まだ仕様を口頭だけで伝えてるんですか？
「伝えたつもり」「聞いたつもり」の認識違いは、開発の手戻りやバグの大きな原因です。仕様が文書化されていないと、開発者ごとに解釈が変わり、完成後に「思っていたものと違う」という事態になりかねません。
例えば、「ログイン機能を作って」とだけ依頼されたとします。
❌ 口頭だけで伝えた場合
上司：
「ログイン画面作っといて！」
開発者：
「分かりました！」
開発者は次のように実装しました。
app.post("/login", async (req, res) => {
const { email, password } = req.body;
const user = await db.findUser(email);
if (user.password === password) {
res.send("Login Success");
} else {
res.status(401).send("Login Failed");
}
});
一見動作しますが、後から次のような問題が発覚します。
- パスワードはハッシュ化する前提だった
- ログイン失敗は5回でロックする仕様だった
- メールアドレスは大文字小文字を区別しない
- 二段階認証が必要だった
- セッション有効期限は24時間だった
結局、
ほとんど作り直しになります。
解決策：明日から使えるベストプラクティス
実装前に、NotionやConfluenceなどへ要件を箇条書きで整理し、関係者全員で認識を合わせましょう。
例えば、次のような仕様書を作成します。
# ログイン機能仕様
## 入力項目
- メールアドレス
- パスワード
## 認証
- bcryptでハッシュ比較
- 失敗5回で30分ロック
## セッション
- JWTを発行
- 有効期限24時間
## エラー
- 認証失敗時は
「メールアドレスまたはパスワードが違います」
を表示する
## セキュリティ
- HTTPS必須
- CSRF対策
- Rate Limit有効
この仕様をもとに実装すると、
✅ 要件に沿ったコード
import bcrypt from "bcrypt";
import jwt from "jsonwebtoken";
app.post("/login", async (req, res) => {
const { email, password } = req.body;
const user = await db.findUser(email.toLowerCase());
if (!user) {
return res.status(401).send("認証失敗");
}
const matched = await bcrypt.compare(
password,
user.passwordHash
);
if (!matched) {
await db.incrementLoginFailure(user.id);
return res.status(401).send("認証失敗");
}
await db.resetLoginFailure(user.id);
const token = jwt.sign(
{ id: user.id },
process.env.JWT_SECRET,
{ expiresIn: "24h" }
);
res.json({ token });
});
文書化するとレビューも速くなる
仕様があると、レビュー担当者もコードだけでなく仕様との整合性を確認できます。
例えば、
仕様
✓ ログイン失敗5回でロック
コード
if (failureCount >= 5)
仕様
✓ JWT有効期限24時間
コード
expiresIn: "24h"
このようにコードと仕様を照らし合わせて確認できるため、レビュー漏れを減らせます。
おすすめの仕様テンプレート
毎回ゼロから書く必要はありません。以下のようなテンプレートを用意しておくと便利です。
# 機能名
## 概要
何を実現するか
## 入力
- 項目
- 型
- 必須/任意
## 処理内容
- 認証
- バリデーション
- 保存処理
## 出力
- 成功時
- エラー時
## 制約
- 権限
- セキュリティ
- 性能要件
## 完了条件
- テスト項目
- 受け入れ条件
明日から実践できるチェックリスト
- 要件を口頭だけで済ませない
- 実装前にNotionやConfluenceへ箇条書きでまとめる
- 曖昧な表現（「できるだけ速く」「いい感じに」など）は数値や条件に置き換える
- 開発・レビュー・依頼者で仕様を確認してから着手する
- 実装後は仕様とコードを照らし合わせてレビューする
まとめ
「伝えた」ではなく「残した」が品質を守ります。
口頭だけの仕様は人によって解釈が変わりますが、文書化された仕様はチーム全員の共通認識になります。実装前に要件を整理し、認識合わせを行うことで、手戻りやレビューコストを大幅に減らし、品質の高い開発につながります。
まとめ
口頭仕様を卒業して、ドキュメント文化でチームの生産性を上げましょう！
#まだやってるんですか #コードの女神はみた #プログラミングスキル
動画で見る
YouTubeショート動画でも同じテーマを解説しています👇
チャンネル登録・高評価もよろしくお願いします 🔔
この記事は「コードの女神は見た！」チャンネルの連動記事です。