ドキュメントとナレッジ管理の原則
- •同期更新: コードや設定に変更を加える際は、ドキュメントを同時に更新する。README、API 仕様、
.env.exampleなどを最新状態に保ち、コードとの乖離を防ぐ。 - •意思決定ログ: 重要なアーキテクチャ変更を行う際は、決定理由と他の選択肢を
docs/decision_log.mdに記録する。 - •コードコメント: コメントには「なぜそうしたか」を記述し、「何をしているか」はコードが説明できる状態を維持する。
ドキュメント更新チェックリスト
- • README.md: 新機能や仕様変更が反映されているか
- • API 仕様書: エンドポイント、リクエスト/レスポンス形式、エラーコードが最新か
- • 環境変数:
.env.exampleに新しい環境変数が追加されているか - • アーキテクチャ図: システム構成に変更があった場合、図も更新されているか
- • トラブルシューティング: 新しいエラーや対処法があれば追記されているか