ドキュメントと設計記録 documentation-and-adrs

これは何？

これは、単にコードを書くだけでなく、その背後にある意思決定を記録するためのスキルです。大切なのは「なぜそのように作ったのか」という背景や考え方を書き残すこと。コードは「何が作られたか」を示しますが、このドキュメントは「なぜそのように作られたのか」と「他にどんな選択肢があったのか」を説明します。これは、将来プロジェクトに関わる人やAIエージェントにとって重要なガイドになりますよ。

これでできること

• 重要な設計決定を記録する
• 選択肢があった時の判断基準を残す
• 公開APIの変更内容を説明する
• ユーザーに影響する機能の変化を記録する
• 新しいメンバーがプロジェクトに参加する時の案内として使う

こんな時に便利

使い方

まず、重要な決定をする時やコードを変更する時に、「なぜその選択をしたのか」をメモするようにしましょう。設計方針（ADR）として記録したり、READMEファイルにクイックスタート方法やアーキテクチャ概要を書くのも効果的です。APIを使う時は、パラメーターや戻り値の説明も一緒に書いておくと便利です。

必要なもの

• 特になし

導入方法

使いこなしのコツ

• 重要な設計決定は必ずADRとして記録しましょう
• READMEファイルには、クイックスタート方法と全体構造の説明を入れておきましょう
• API関数を使う時は、パラメーターと戻り値の説明も付け加えましょう