ホーム自己紹介ブログ
NO.499
DATE2026. 10. 09

Design Doc, ADR, RFC

趣味レベルの開発であっても、最近では DesignDocやADRを書き残すようにしています。

ナイモノは読めないから

Design Doc のような機能に関する仕様や、
ADR のような全体のアーキテクチャに関する仕様など、
意思決定は山ほどあります。

作った結果についてはコードベースに残っているため、
機能の振る舞いや具体的な設計については(AIが)読めばわかります。
しかし作っていないもの、例えば見送ったものについては読み取ることができません。
仕様を決めるにあたって、見送る過程の議論・思考は貴重な情報 で、
それを含めて意思決定です。

この ナイモノを言語化して記録 をすることで、人やAIライクに仕事を進めることができます。

リポジトリにコミット

その言語化したテキストは、リポジトリにそのままコミットして残す様にしています。
これはリポジトリに入っていることで、わざわざAIにプロンプトチューニングしなくてもそれを踏まえて設計してくれる、
そんな気がします。(笑)
(GitHub issueなど外部に纏めるよりもシームレスと思ったり)

実際私の個人開発において、開発した機能仕様について毎回AIに伝える必要がなくなり、
機能名を改善する際に文脈コンテキストを踏まえて作ってくれます。
これは結構助かりました。

個人ではなくチームにおいては、さらに良い点があります。
チームで開発すると効率化を求めると、情報格差 が生まれる場合があります。
ある人は知っているけど、あの人はしらない。
そういう情報格差があると、レビュー精度だけでなくコミュニケーションで困ることもあります。
その情報格差を平すために、この資料を残すことは大事なことと思います。

意見を募る RFC のファイルも同じくリポジトリにコミットしておくと良いでしょう。
個々人の意見の集合体が記録されることで、チームとしてはどういう方向に舵を切ったのかを知ることができます。
どういう考慮があったか、どういう懸念があったか、そういう背景を残すというのは将来の自分たちの首を絞めずに済みます。

終わりに

資料を書く面倒さは、今の時代はほぼノーコストです。
メンテナンスしないために、その時点のスナップショットと扱うとやりやすいです。
ぜひ、仕様をリポジトリにコミットしましょう。

仕事
個人開発

-

読者になる

|

シェアする

|

silverbirders

silverbirder

Webソフトウェアエンジニア
個人ブログキュレーション こぶりー 運営

ブログを応援する

この記事がよかったら、お布施という形で応援してもらえるとうれしいです。

おふせぼたん

※ ログイン不要で投稿できます。

※ 同じブラウザから投稿を削除できます。

0

読み込み中...

次の記事へ前の記事へ

関連する記事

タグ「仕事」の記事

貴重なアイデア

今日はお仕事(Web関連)のことでも書こうと思います。 今の時代、アイデアがあれば 形にするまでの道のりは比較的楽になりました。 昔だと、形にするためには技術的な調査や設計方法について下調べをした上で、せっせと作っていました。 それがいまだ

2026年10月30日

仕事
Codex, Claude のピン留めがお気に入り

Codex や Claude のデスクトップアプリにあるピン留め機能が気に入っています。 ピン留めというメタファ 髪の毛を束にしてまとめるためのピン留めや、 コルクボードに紙を止めるためのピン留めなど、 何かを固定するというメタファがピン留

2026年10月05日

仕事
AI
尼崎のおもいで

今日、天ぷら屋さんで昼食を取りました。 お隣の席が職場グループ8人組でした。 なんとなく、尼崎での思い出が蘇りました。 毎日一緒 尼崎にある職場で出勤していた頃、その当時は私はまだ独身でした。 同じチームで働く4名ぐらいのメンバーと、 毎日

2026年09月03日

雑談
仕事

タグ「個人開発」の記事

個人サイトのリニューアル 7回目

個人サイト、7回目のリニューアルをします。 個人が自由に練習できる場、それが個人サイトの良いところです。 今まで 静的コンテンツを必ずホスティングする構成を変えずに、いろいろなものを試してきました。 最初は、Hugo でポートフォリオとして

2026年11月17日

個人開発
利用規約って何かズルい

何かしらのサービスを利用しようとする際に、利用規約という超長文の文章を読むように誘導されることがある。 例えば、 EC サイトなどでアカウント登録する際に利用規約の文章を最後までスクロールしたら登録ステップが進む仕組みがあったりする。 読ん

2026年11月12日

個人開発
『個性を磨くUI観点』本を執筆

AI ぽい UI デザインを脱したい人向けの本を執筆しました! 文字・余白・形・色・操作 など合計8つの観点で、UI デザインを考える本になります。 ぜひお手に取って、みてもらえればと思います。 対象読者は、 UI デザインを考える人、作る

2026年11月09日

個人開発
デザイン
← ブログ一覧へ