# 執筆ガイド（（サイト名をここに書く））
<!-- 使い方: このファイルを docs/writing_guide.md という名前でコピーし、（）の部分と空欄を自分の値で埋めてください。
「AIのクセ禁止リスト」と「FAQのソース強制」は、そのまま使える共通ルールです。 -->
記事の書き方は、このファイルが正です。`blog-writer` が執筆・書き直しをするとき、レビュアーが記法や広告配置を検査するときに読みます。公開ゲートとレビュー体制は `CLAUDE.md` を見てください。
このファイルでは、最終判断をする人を「運営者」と呼びます（呼び方は `config.yaml` の `operator_name` で変えられます）。
---
## frontmatter の仕様
記事ファイルの先頭に書く項目です。自分のサイトで使う項目だけを残してください。
| 項目 | 必須 | 内容 |
|---|---|---|
| `title` | （必須／任意） | （例: 記事タイトル。32字前後） |
| `slug` | （必須／任意） | （例: URL になる英数字） |
| `description` | （必須／任意） | （例: 検索結果に出る説明文。手で書く。字数の目安） |
| `category` | （必須／任意） | （例: カテゴリ名。選べる値の一覧） |
| `published` / `updated` | （必須／任意） | （例: 公開日・更新日。本文の更新日表示と一致させる） |
| （ほかの項目） | | |
## 記法
このサイトで使う書き方の一覧です。標準の Markdown と違う独自の記法があれば、必ずここに書いてください（レビュアーは、ここに無い記法を「記法崩れ」として指摘します）。
| 記法 | 表示される形 |
|---|---|
| `## / ### / ####` | 見出し（本文に h1 は書かない） |
| `**太字**` | 強調 |
| `[文言](URL)` | リンク |
| （囲み枠の書き方） | （例: 結論の囲み・注意の囲み） |
| （出典の書き方） | （例: 出典リンクの決まった形） |
| （FAQ の書き方） | （例: 質問と回答の決まった形） |
| （広告の入れ方） | （例: 広告を差し込むタグ） |
- （記法の注意点を書く。例: 囲み枠は必ず閉じる。表の注記は表の外に書く）
## 字数基準
- **数え方**: （例: 本文だけの字数。`scripts/review_metrics.py` の実測字数を使う）
- **字数を目的にしない**。下限に届かないときは水増しせず情報を足す。上限を超えるときは、先に記事の分割を考える。
- 範囲は、自分のサイトのアクセス実測（読まれている記事の長さ・滞在時間）を見て決めてください。ここに「正解の既定値」はありません。
| カテゴリ（記事の種類） | 字数の範囲 | 適用 |
|---|---|---|
| （カテゴリ名） | （ ）〜（ ）字 | （例: これから新しく公開する記事から） |
| （カテゴリ名） | （ ）〜（ ）字 | |
| （カテゴリ名） | （ ）〜（ ）字 | |
- 内容が薄いと見なす下限: （ ）字未満（全記事が対象。法務レビュアーがリスクとして扱う）
- 既存の記事にさかのぼって適用するか: （例: しない。次に書き直すときから適用する）
- （範囲を決めた根拠を書く。いつ・何を測って決めたか。見直すときの手掛かりになる）
## AIのクセ禁止リスト
**初稿の質を最も変えるのはここです。**判定の軸は「その文（その語）を消しても、読者が受け取る事実は変わらないか」。変わらないなら書きません。
- ❌ **情報量ゼロのつなぎ文**: 「いかがでしたか」「ここまで見てきました」「それでは見ていきましょう」など、消しても事実が減らない文。
- ❌ **章末の気の利いたまとめの決まり文句**: 「ぜひ参考にしてください」「検討してみてはいかがでしょうか」の連発（記事末のまとめの章で1回は可）。
- ❌ **飾りの副詞**: 「ぐっと」「きっと」「とても」「非常に」「かなり」の多用（1記事に2回までが目安。数値で言えるなら数値で）。
- ❌ **あいまいな量表現**: 「かなり安い」→ 実際の金額・実測値に置き換える。
- ❌ **指示語の多用・主語の省略**: 「これ」「それ」が2文続いたら、具体的な名詞に戻す。
- ❌ **未公開の記事の予告**: 「〜は別の記事で扱う予定です」→ 公開済みの記事があれば内部リンクにする。無ければその場で最小限の答えを書くか、何も約束しない（リンクできない予告は読者にとって価値がなく、書いた側に約束だけが残る）。
- ⭕ **体験談の手触りを残す**: 運営者の体験の素材（つまずき・意外だった点・一人称の感触）を、カタログのような説明文に均さない。体験談を創作しない。
- （書き直しのたびに運営者が直している言い回しがあれば、ここに足していく）
### FAQのソース強制
FAQ は**AI の想像で作りません**。出どころは次のいずれかとし、書くときにどれに由来するかを確認できるようにします。
1. 検索の実クエリ（アクセス解析で実際に入ってきている検索語）
2. 検索のサジェスト・関連する質問
3. Q&A サイトに実際にある質問
4. `research/` にある裏取り済みの疑問
### 検出パターン
ライターは書いたあとの自己チェックに、レビュアーは検索の補助に使います。
```
いかがでし(た|ょう)か|見ていきましょう|ここまで(見て|読んで)|ぜひ参考に|検討してみては|ぐっと|きっと.{0,6}(はず|でしょう)
```
ヒットしたら即NGではなく、上の判定の軸にかけます（文脈の中で情報を持っている使い方は許容します）。
### 初稿スナップショット
新規記事・大幅な書き直しの初稿ができた時点（レビューを反映する前）で、`reviews/drafts/{slug}_initial_{YYYYMMDD}.md` にコピーを保存します。最終版と比べて「毎回直されている箇所」を見つけ、このリストに足していくためです。
## 画像
- 置き場所: （例: `public/assets/images/{slug}/`）
- 代替テキスト（alt）と幅・高さは必須。**キャプションは撮影した事実と一致させる**（測っていない値・していない検証を書かない）。
- ⚠️ 撮影するときは、背景に郵便物や家族の写真など、個人が分かるものを写さない。
- （形式・圧縮・撮影の分担を書く）
## 広告配置ルール
広告を置かないサイトは、この章を消してください。
- 1記事に置く広告の上限: （例: 本文中 個まで＋記事末 個）
- 置く位置: （例: 結論の直後、比較表の直後、記事末）
- **記事の内容に合う商品だけを置く**。合う商品が無い記事には広告を置かない。読者の検索意図と商品を一致させる（例: すでに買った人向けの使い方の記事に、本体の広告を置かない）。
- 広告リンクのコードは、運営者が管理画面で発行した実物だけを使う。同じ商品を1ページに重複して置かない。
- 広告である旨の表示（PR 表記・開示文）の置き場所: （例: 記事冒頭と記事末。法令上必須なので消さない）
- 広告リンクに付ける属性: （例: `rel="sponsored nofollow"`）
- （利用している ASP の規約で決まっている配置の制限を書く）
MIT ライセンスで配布しています。