🍄

ドキュメント駆動開発を試しているログ

に公開
ドキュメント駆動開発
idea

🧩 背景（As-Is）

現在の課題や違和感について書きます。

  • ドキュメントが無い
  • あっても更新されない
    • そもそもドキュメントを更新する工数が無い
    • 現在の仕様が常に不明なのでBlameしてPRとチケット掘って作業している

🎯 目的・理想像（To-Be）

  • コードと一緒にドキュメントも管理できる

🔨 取り組んだこと（変更点・工夫）

git管理下にドキュメントを作成する

docs/
├── my-vault/              ← Obsidian Vaultのルート
│   ├── .obsidian/         ← Obsidianの設定フォルダ
│   ├── Templates/         ← テンプレート保存用フォルダ
│   │   └── new-dev.md     ← （例）新規開発用記事テンプレ
│   └── config.yml     ← obsidianhtmlで使う設定ファイル
└── output/
    ├─ html
	├─ md
	└─ mod

ディレクトリ構成はあんまり気に入っていない。Obsidianを使っているのは私がObsidian好きなだけです

ドキュメントを書く

ざっくりでいい

# 広告モデル

- 広告種別: 必須
  - 画像
  - 動画
- 広告サイズ: 必須
  - 縦長
  - 横長
  - 正方形
- URL: 必須
- 代替テキスト: 任意
- タグ: 必須、文字列配列

Cursorに指示

docs/Models/広告.mdを参照し、app/models/advertisement.rbを記述してください

一部変なコード書いてた

# コールバック
before_validation :normalize_tags
  
private
  
def normalize_tags
  return if tags.blank?
  # タグが文字列の場合は配列に変換
  if tags.is_a?(String)
    self.tags = tags.split(',').map(&:strip).reject(&:blank?)
  elsif tags.is_a?(Array)
    # 配列の場合は空文字列を除去
    self.tags = tags.reject(&:blank?).map(&:to_s)
  end
end
  • tagsはstring[]型(PostgreSQL)。before_validationに来るのはActiveRecordの型変換が適用された後なので、既に配列型である。ここで配列か文字列かを判定するのは遅い
  • カンマ区切り文字列をtagsに渡したときの挙動も変
app(dev)> Adv = Advertisement.new  
=> #<Advertisement:0x00007f844c1586c8 id: nil, title: nil, link_url: nil, image_url: nil, active: false, tags: [], created_at: nil, updated_at: nil, ad_type: "image", ad_size: "square", alt_text: nil>  
app(dev)> Adv.tags = "タグ1,タグ2,タグ3"  
=> "タグ1,タグ2,タグ3"  
app(dev)> Adv.tags  
=> ["\x82\xBFグ1", "タグ2"]

アクセサメソッドで分割する形に修正

def tags=(value)
  if value.is_a?(String)
    # 文字列の場合は配列に変換
    super(value.split(',').map(&:strip).reject(&:blank?))
  else
    # 配列の場合は空文字列を除去
    super(value.reject(&:blank?).map(&:to_s))
  end
end

Cursorに指示

ありがとうございます。今の更新を元に、docs/Models/広告.mdに詳細を記述してください

(書いてもらう)

ありがとう。関連するページとリンクさせたいので、wiki記法でリンクを作成してもらえますか。ひとまず広告モデルへのリンクと、RansackやKaminariなど関連パッケージも一覧を作ってリンクしたいです

Cursorに指示

ありがとうございます。次は、app/models/advertisement.rbに対するテストをspec/models/advertisement_spec.rbに記述してください

一部要らないテスト書いてたり変なことをやっていたので修正（文字コードとか型のテストまでやろうとする）（何してんのと質問をするとコードの修正を始める）

Cursorに指示

ありがとうございます。今の変更を元にプルリクエスト用のコメントを書いてください

📈 効果・結果（Before / After）

メリット

  • 労力少な目で回せる
  • プルリクエストにドキュメントとコードの変更が同時に乗るので見やすい

デメリット

  • 変更が膨らみがち
  • たまに嘘を言う（CSS全然当たってないのに素晴らしいUIを作ったかのようなことを言ってくるなど）

📝 まとめと学び

  • テンプレートは作った方がいい
    • PRを書かせるためのテンプレート
    • 仕様書（設計書）を書かせるためのテンプレート
      • これはモデル用とかなんとか分けた方が良さそう
    • →一旦プロジェクトのテンプレートを作ってしまえば予後が良さそう
  • 初手のドキュメントも細かく書けるに越したことはないけど細かく書かなくても割とやってくれる
    • 余計な気を利かせてくれることは多い
  • あとなんか根本解決より「臭いものに蓋」の方向で動きがちに見える
  • コンソールでコマンドを叩く必要があるようなのはうまく動いていない。この辺はDockerで作業しつつWindowsでCursor使ってるせいもありそう

あとでドキュメントの静的ホスティングもやりたい

🔗 参考リンク・関連資料

GitHubで編集を提案

Discussion