今週うまくいったドキュメンテーション

ドキュメンテーションは大変だ。知識を絞り出すのと文章を組み立てるのは別の知的作業で、それを同時にやらなければいけない。
私はよどみなく文章を書くのが得意ではないので、大いに生成 AI の力を借りたい。

今週やってみてうまくいった方法を書き留める。

目次
成功事例①: ざっくり書いて、リライトしてもらう
- モデルごとのリライト能力
- 大幅なリライトのうれしい副作用
成功事例②: つれづれに書いて、リライトしてもらう
ちょっとしたテクニック
- 文章の全文を毎回渡す
- いろいろなモデルにレビューを投げてみる
まとめ

成功事例①: ざっくり書いて、リライトしてもらう

データ集計での期間の考え方についてガーっと書いた。読みづらいなぁと思いながら書いているので筆が重い。

# 変数による集計期間指定について

集計期間は dbt 変数の `start_date`, `end_date` で指定します。

## `start_date`, `end_date` の意味論

最新日付の集計だけでなく、過去日付を指定してバックフィル集計を実行するために `start_date`, `end_date` は使われます。

※ バックフィル集計: データが入っていない過去日付に対して集計を実行したり、過去日付に対して再集計すること

### 日次集計の場合

日次集計 (毎日集計) を想定したモデル models/summary/arppu_1d.sql に対して `{ "start_date": "2025-02-01", "end_date": "2025-02-03" }` と指定して集計した場合、これは「arppu_1d の日次集計を `2025-02-01`~`2025-02-03` の3日分同時に実行せよ」という意味になります。

### 週次集計・月次集計の場合

週次集計, 月次集計については事情が異なってきます。週次集計を想定したモデル models/summary/arppu_7d.sql に対して `{ "start_date": "2025-02-01", "end_date": "2025-02-03" }` と指定して集計した場合、これは「arppu_7d の週次集計を `2025-02-01`~`2025-02-03` を **含む週に対して** 同時に実行せよ」という意味になります。

したがって、`2025-02-01`~`2025-02-03` は2週間にまたがっていますから、2週分の週次集計が同時に実行されるようにモデルを実装するのが妥当になります。

これを Gemini に渡してリライトを依頼した。

dbt でモデルを実装するときのあり方についてドキュメントを書いています。理解度の高い私が書いたので内容は正確です。しかし不慣れなプロジェクトメンバーには読みづらいかも。文章を読みやすくするための提案。具体的な文章の提示をおねがいできますか。

そうすると跡形もなく書き換えられてこのように返ってきた。

## 修正案：dbt モデルにおける集計期間指定のガイドライン

このドキュメントでは、dbt 変数 `start_date` と `end_date` を使った集計期間の制御方法と、その考え方を解説します。

---

### 1. `start_date`, `end_date` の役割

これら 2 つの変数は、**「どの日付（期間）の集計結果を作成したいか」**を指定するために使用します。
日々の自動実行だけでなく、過去のデータを遡って集計し直す「バックフィル」の際にもこの変数を利用します。

> **用語解説：バックフィル**
> データの欠損を埋めたり、ロジック変更に伴い過去の日付に遡って再集計を行うこと。

---

### 2. 集計単位ごとの解釈（意味論）

指定した期間が「どのアウトプット（行）」を作成するのか、集計単位によって解釈が異なります。

#### 日次集計（1d モデル）の場合

指定された期間を **1日ずつ** 実行します。

* **例:** `{ "start_date": "2025-02-01", "end_date": "2025-02-03" }`
* **結果:** `02-01`, `02-02`, `02-03` の **3日分** のデータが作成されます。

#### 週次・月次集計（7d / 30d モデル）の場合

指定された期間を **「含む」週や月** をすべて実行します。

* **例:** `{ "start_date": "2025-02-01", "end_date": "2025-02-03" }`
* **ルール:** 週の区切りが日曜〜土曜の場合
* `02-01`(土) は、前週のグループに含まれます。
* `02-03`(月) は、次週のグループに含まれます。


* **結果:** この期間は 2 つの週にまたがるため、**2週分** の集計が実行されます。

読みやすくなった。要点を押さえつつ私よりも断然文章がうまい。

モデルごとのリライト能力

いくつかのモデルにリライトを依頼してみた。

Claude Code (Opus 4.5): 元となる文章を尊重する、大幅なリライトはしてくれない
Gemini 3: 大幅にいい感じにリライトしてくれる
ChatGPT 5.2: 大幅にいい感じにリライトしてくれるが、テイストが ChatGPT すぎる

Claude Code はエディタでそのまま動いてくれるから便利だけど、大幅にはリライトしてくれないので物足りなかった。

大幅なリライトのうれしい副作用

私の文章テイストを捨て去って大幅にリライトさせるなかで「生成 AI の読み違い」が浮き彫りになるのがうれしい副作用だった。
例えば、

私の文章: 「めぐみのあめだ」
リライト: 「キャンディーもらった」

となっていたら「いやそっちの "あめ" じゃないから」となる。

実際にはこんな単純な読み違いは起こらないが、ドメインに由来する微妙な概念の読み違いは発生する。
そんなときには「ここの〇〇という概念は××とは別のもので」と説明した後で「先ほどの概念が明確に伝わるようにドキュメントに反映してください」と指示すると、より読み違いにくい文章にブラッシュアップしてくれる。

生成 AI が読み違えるということは人間も読み違えるということだ。理解しづらい概念や紛らわしい表現を事前にピックアップしてより分かりやすい表現に書き直せるのはうれしい。

成功事例②: つれづれに書いて、リライトしてもらう

いろいろなトピックは思いつくものの、文章の体裁にするのが面倒なときがある。そんなとき思いついたことを思いついた順に書いて生成 AI に清書してもらうのがいい。

我々のシステムの集計分析をdbtでやるプロジェクトを進めています。
dbtモデルなどを作ったときのレビューをAIエージェントにさせたい。そのためにレビューガイドラインを作ろうと思います。
私が徒然に「〇〇は××じゃないといけなんだよねー」と書き連ねるので、ある程度まとまったところでレビューガイドラインの体裁にしてもらえますか。

まず「つれづれに書くよ」と宣言する。するとこのように応じてくれる。

まずは、私がガイドラインをまとめる際の**ベースとなる構成案**を作成しました。あなたがこれから書き連ねる「こだわり」や「ルール」を、以下のどのカテゴリに当てはめるかイメージしながらアウトプットしていただければと思います。

---

## dbtレビューガイドラインの構成案（イメージ）

AIエージェントが判定しやすく、人間が理解しやすいように、以下のような章立てで整理する予定です。

1. **プロジェクト構造・モデルの責務**
* どのレイヤー（Staging / Intermediate / Marts）に配置すべきか。
* モデル間の依存関係（Sourceの直接参照禁止など）。

2. **SQLコーディングスタイル**
* CTE（共通テーブル式）の書き方。
* 予約語のケース、インデント、カンマの位置。
* SELECT * の禁止など。

3. **命名規則**
* テーブル名、カラム名、エイリアスの付け方。
* フラグや日付型の接尾辞ルール。

4. **テストとドキュメント**
* 必須のテスト（Unique, Not Nullなど）。
* `description` の記述レベル。

5. **パフォーマンスとベストプラクティス**
* 不要なJOINの回避。
* データ型のリキャストやタイムゾーンの扱い。

よくあるトピックを最初から頭出ししてくれている。優秀。

ここから思いつくままにぐだぐだと書いていく。

> CTE（共通テーブル式）の書き方。

まず CTE は積極的につかってほしい。
そんで CTE の名前はアンダースコア `_` から初めてほしい。普通のテーブル名・普通のカラム名と区別できるから。

---

DATE型のカラムについて、タイムゾーンは Azia/Tokyo だな。
いまのところは日本市場向けにビジネスしているため。

---

dbtの `source()` や `ref()` を必ず使おう。
`some_project.some_dataset.some_table` という形で参照しているモデルを定期集計で動かすべきではない。実装途中・実験中ならありえるかもだけど最終的なレビュー時点まで残っていたらそれは異常。

こんな感じ。

そうするとしっかりしたレビューガイドラインの形で文章が出てくる。
トピックの並び替えやグルーピングも問題なし。言葉尻もちゃんと整えてくれる。

ちょっとしたテクニック

文章の全文を毎回渡す

生成 AI に元となるドキュメントを渡して「読みやすくして」など指示すると、元の文章の要点を押さえつつリライトしてくれる。

ところが、そこから質問やディスカッションを何巡かして「それをドキュメントに反映して」と指示すると、元の文章の再現性が低下する。
生成 AI からすると何巡かの会話が挟まったことで、過去に渡された文章を半分忘れてしまっている状態だ。

そこでリライトや追記を要求するときは毎回、最新版の文章を渡すようにする。

ここまでの議論をふまえて注意点を追記して。

```markdown
(ここに文章を全文貼る)
```

そうすると、生成 AI は貼られた文章を元にして追記などしてくれる。

いろいろなモデルにレビューを投げてみる

同じ文章を渡してもモデルが異なると着眼点も異なる。ドキュメントを書き終えたら、いろいろなモデルに渡して意見をきいてみるといい。

私が経験したパターンは、

Gemini 3: 「こんなトピックも追記してみては？」と提案
Claude Code (Opus 4.5): 「ここの日付間違えてませんか？」と指摘
GitHub Copilot: 「ここタイプミスでは？」と指摘

こんな感じで各々のモデルが少しずつブラッシュアップしてくれた。
面白いのは生成 AI なら真っ先に見つけそうなタイプミスを、3番手の Copilot しか指摘してくれなかったことだ。

たぶんレビュー依頼するときのプロンプトを工夫すると全ての指摘事項を1つのモデルに出させることもできるんだけど、ちゃんと考えるのはだるいのでたくさん投げてみるのもいいと思う。

まとめ

生成 AI をうまく使うことで「自分の文章下手だなー」と自分を呪いながら仕事をせずに済むので良い。

私からは以上です。

無駄と文化

実用的ブログ