仕様書を残す

コードは「今どう動くか」を示しますが、「なぜそうしたか」「何が正しい姿か」は示しません。弊社では、リポジトリの.docsディレクトリに仕様書を残します。製品の目的、対象利用者、画面や機能の仕様、そして採用しなかった案とその理由です。

見た目の方針と部品の使い分けは、UIの観点で扱うDESIGN.mdなどのデザイン文書を参照します。同じ判断を仕様書にもコピーせず、目的や機能の仕様から辿れるようにします。

誰のための仕様書か

まず自分のため、次にこの製品を触るすべての人とAIのためです。Claudeは会話とコードから読み取れることしか知らないため、仕様書があると、会話をまたいでも同じ全体像を渡せます。部分ごとの開発で起きる全体のぶれを抑える土台にもなります。

決まったことは会話の外へ出す

弊社では、仕様や方針に合意した時点で、共有するファイルへ反映してもらいます。会話の記憶だけを保存先にすると、次の作業で何を前提にすればよいか確かめられないためです。製品の詳しい仕様と判断は.docsへ、作業のたびに必要な前提はCLAUDE.md（Claude向けの指示ファイル）へ、繰り返す手順はSkill（再利用できる手順書）へ残します。同じ内容を複数の場所へコピーせず、正本を参照します。

次の会話では、今回の作業に関係するファイルを指定して読んでもらいます。長い作業の中断・再開でも、会話だけに頼らず現在の差分と検証結果を確かめます（並行作業と長時間の作業）。

この会話で合意した仕様と判断の理由を.docsへ反映して。今後も守る約束はCLAUDE.mdから参照できるようにして

CLAUDE.mdに残す前提

弊社では、次の項目のうち製品に関係するものを記録します。公開範囲や本番運用の有無が違えば、同じ「共有して」「初期化して」という依頼でも影響が変わるためです。現在どうなっているかに加え、維持する理由と、変更してよい条件を残します。

すべてが決まるまで作業を止めず、分かっていることから書きます。「未確認」「未決定」「該当なし」を区別し、推測で埋めません。長い仕様や手順は参照先を示し、CLAUDE.mdには判断に必要な要点を残します。

公開範囲と利用者

• リポジトリの公開範囲: public・privateなど現在の設定。コードと履歴を誰に見せる方針か、公開範囲を変えてよいか、誰が判断するか
• 製品の利用対象: 社内の従業員、特定の顧客、取引先、一般の利用者のどこまでを対象とするか。部門や役割による違いがあるか
• 画面や資料の閲覧範囲: 誰でも開けるか、ログインが必要か、指定された人だけか。本番と確認用の画面で範囲が違うか
• 外部への提供予定: コード、画面、資料、APIを外へ公開・販売・納品する予定があるか。未発表の内容や契約上の制限があるか

リポジトリがprivateであることと、製品が社内向けであることは別です。privateのコードから一般公開のサービスを配信する場合もあるため、それぞれを記載します。

目的と運用の状態

• 目的と優先順位: 誰の何を解決する製品か。速度、使いやすさ、費用など、判断がぶつかったときに何を優先するか
• 本番運用の有無: 試作中、公開準備中、本番運用中、保守のみ、終了予定のどの状態か。すでに利用者や保存済みのデータがあるか
• 規模と運用期間: 利用人数、データ量、利用が集中する時間帯、試用期間、今後も使い続ける予定
• 影響を受ける業務: 止まると誰が何をできなくなるか。許容できる停止時間や、変更してよい時間帯があるか
• 所有者と担当者: 製品、ドメイン、契約、運用アカウントを誰が管理するか。方針の判断者と障害時の連絡先

データと外部への影響

• 扱う情報: 個人情報、顧客から預かった情報、社内限定の情報を扱うか。保持期間や削除に関する約束があるか
• 確認に使うデータ: 架空のデータか、利用を認められたテスト用データか。本番の実データを作業対象にしてよい条件があるか
• 環境の区別: 本番・プレビュー・開発の確認先と役割。今の作業場所がどの環境で、本番へ影響する接続があるか
• 外部との連携: メール、通知、決済、データ連携などの接続先。本当に送信・課金・更新されるものと、確認用のものの区別
• 費用と上限: 課金されるサービス、請求先、予算、利用上限。通知や停止を判断する担当者
• 復旧の条件: 何をどこまで戻せるか。バックアップと復旧手順の確認先、削除や送信など取り消せない操作

秘密のキーや実在の個人情報は、前提を説明するためでもCLAUDE.mdへ書きません。情報の種類と安全な確認先を示します。publicのリポジトリでは、指示ファイルや参照先に載せる説明も公開可能な範囲に収めます（トークン・APIキー、個人情報・認証・決済）。

変更と引き継ぎの条件

• 許可する操作: 調査、編集、共有、本番反映のどこまで進めてよいか。公開範囲の変更、データ削除、外部送信など判断を返す操作
• 守る互換性: 保存済みのデータ、共有済みのURL、他の製品との連携を維持する必要があるか
• 今回扱わない範囲: 変更しない機能、他の担当者が作業中の場所、今回の目的に含めない改善
• 利用環境: 対応する端末、ブラウザ、言語、社外から使うかどうかなど、利用者の条件
• 決まっている方針: 採用する技術、見た目の方針、契約や納品の条件。仕様書やDESIGN.mdなどの正本の場所
• 確認と完了の条件: どの操作や結果を確認すれば完了か、誰が確認するか。確認できない環境や既知の問題があるか
• 未決定の事項: まだ決めていないこと、確認待ちの相手、仮の判断と見直す時期

この一覧に沿って、分かっている製品の前提をCLAUDE.mdへ整理して。
公開範囲、利用対象、本番運用の状態は別々に書いて。未確認のことは推測せず、確認が必要な項目として残して

運用開始や公開範囲の変更など、前提が変わった時点で更新します。指示ファイルの読み込み条件や設定の管理方法は、開発者向けのClaude Codeの運用知見で扱います。

最新に保ち、コードとの差分をなくす

仕様書は放置すると古くなり、コードと食い違い始めます。かつては差分を人手で追い続ける根気が続かず、古い仕様書は捨てられがちでした。今は、コード全体と仕様書を突き合わせて差分を洗い出す作業を、AIが何時間でも続けてくれます。定期的にお願いして、仕様書を正本に保ちます。

.docsの仕様書とコードを突き合わせて、食い違っているところを一覧にして
それぞれの根拠と、仕様・コードのどちらを直す案かを説明して。更新はまだしないで

どちらが正か

食い違いが見つかった時、機械的にどちらかへ揃えるのではなく、どちらが正しいかを判断します。仕様が正しければコードを直し、コードが正しければ仕様を更新します。この判断は製品の目的に関わるため、人が行います。仕様書を正本とした運用の全体像は製品で扱います。

今合意した修正方針で、該当する仕様書とコードを更新して。判断が残っている箇所は変更せず残して