はじめに

「仕様は口で言ったから大丈夫！」

え、まだ仕様を口頭だけで伝えてるんですか？口頭伝達チームはドキュメント化チームより手戻りが平均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ショート動画でも同じテーマを解説しています👇

https://youtube.com/shorts/F2CNkQYetvA

チャンネル登録・高評価もよろしくお願いします 🔔

この記事は「コードの女神は見た！」チャンネルの連動記事です。