| name | evergreen-writing |
| description | Markdown ドキュメント (README, 設計書, .claude/rules/, docs/) や、コード内の
公開関数 JSDoc / docstring / 非自明ロジックへのコメントを書く・編集するときに
使うスキル。「半年後の読者が誤解しない文章」を成立させるためのチェックリスト。
以下の場面で必ず発動する:
"ドキュメントを書いて", "README を更新して", "設計書を書いて",
"コメントを足して", "JSDoc を書いて", "docstring を書いて",
"ルールを追加して", "プランを書いて", "仕様をまとめて",
".claude/rules に追加", "docs/ に追加", "PR description を書いて"
Markdown 文書 (.md / .mdx) や code comment の Edit/Write を行う前後に
チェックリストを通す。
|
Evergreen Writing Skill
「今読んでも、半年後に読んでも、新しいメンバーが読んでも、誤解なく意味が通る文章」を書くためのワークフロー。
このスキルは /.claude/rules/evergreen-documentation.md の 4 大原則（Evergreen / Why-First / SSOT / Reader-Friendly）を、執筆中の チェックリスト形式 で適用する。
いつ発動するか
| 場面 | 適用 |
|---|
.md / .mdx の Write/Edit | 必須 |
.claude/rules/ への追加・編集 | 必須 |
docs/ への追加・編集 | 必須 |
公開関数 (export) の JSDoc / docstring を書く | 必須 |
| 非自明ロジックへのコメント追加 | 必須 |
| PR description / commit message | 推奨 |
| 自明なゲッター・型から明らかな関数へのコメント | 対象外（そもそも書かない） |
| CHANGELOG / .changeset / docs/plans/ | 対象外（履歴を含むことが正当） |
ワークフロー
Phase 1: 執筆前 — 読者と目的を特定する
文書を書き始める前に、以下を TodoWrite に展開する:
- 読者は誰か — 新メンバー / オペレーター / 同僚 / 半年後の自分
- 読者が知りたい WHY を特定する — 何を理解したくて読みに来るか
- SSOT 確認 — 既存のどこかに同じ情報がないか
grep -r する
- 構造を決める — 概要 → 使い方 → 詳細の順か、別の論理順序か
- 専門用語の棚卸し — 初出で説明 or リンクを張る用語をリストアップ
SSOT 確認で既存があれば:
- 既存を更新する（新規作成しない）
- 既存からの参照を張る
- どうしても両方必要なら片方を「正」と明示する
Phase 2: 執筆中 — 4 大原則を意識する
Evergreen（時間依存を避ける）
書きながら 以下の表現を意識的に避ける:
NG ワード: 以前 / 従来 / これまで / 現在は / 現状 / 目下 / 今後 / 将来 / 予定
NG 参照: PR #N / commit SHA / 〇〇さん / YYYY-MM-DD / YYYY 年 M 月
書いてしまったら以下に書き換える:
| 書いた表現 | 書き換え |
|---|
| 「以前は X だったが Y にした」 | 「X は <理由> のため Y にしている」 |
| 「現在は Y を使っている」 | 「Y を使う」 |
| 「今後 Z する予定」 | 削除（issue/plan に書く）or「Z 化する場合は <条件>」 |
| 「PR #1234 で導入」 | 削除（git log の仕事） |
| 「田中さんが書いた」 | 削除（git blame の仕事） |
Why-First（WHAT を書かない）
書いた段落ごとに「これは WHAT か WHY か」を自問する。WHAT ならコードや構成図に任せて削る。
NG: 「ユーザー ID で fetch する」（コードを見れば分かる）
OK: 「外部 API のレートリミット上、bulk fetch ではなく個別 fetch にする」
SSOT
執筆中に「これ、別の場所にも書いてないか？」を都度確認する。書いていたら参照に切り替える。
Reader-Friendly
- 段落が 5 文を超えたら分割を検討
- 同じ構造の対比が出てきたら表に変換
- 二重否定が出てきたら肯定形に書き換える
- 「これ」「それ」が指すものが直前にあるか確認
Phase 3: 執筆後 — セルフチェック (3 ラウンド)
書き終えたら、以下を 3 ラウンド回す。1 ラウンドで全部直そうとしない。
ラウンド 1: Evergreen / Why-First
LC_ALL=C grep -nE '(以前|従来|これまで|今後|将来|現在は|現状|目下|予定)' <file>
LC_ALL=C grep -nE '(PR\s*#[0-9]+|commit\s+[0-9a-f]{7,}|さん(が|の|作|担当))' <file>
ヒットしたら原則 1 のテーブルに従って書き換え。
ラウンド 2: Reader-Friendly
ファイル全体を 冒頭から 読み直し:
ラウンド 3: SSOT / 重複
Phase 4: 完了確認
ガード機構との連携
このスキルは以下の機構と多重防御を構成する:
| 層 | 役割 |
|---|
.claude/rules/evergreen-documentation.md | 規範（このスキルが参照する原則） |
| project の構造化 lint ルール (例: ast-grep) | コードコメントの時間依存表現を検知 |
| project の構造化 lint ルール (例: ast-grep) | コードコメントの履歴・担当者参照を検知 |
| project の post-edit doc-lint hook | .md 編集後に違反検知 |
| このスキル | 執筆前後のセルフチェックでハーネスをすり抜けた違反を捕まえる |
機械検知（hook / ast-grep）は high-precision な regex しか書けないため、
「Plain Language」「Cognitive Load」「Progressive Disclosure」「SSOT」のような
主観判断が必要な原則 はこのスキルでカバーする。
アンチパターン
| やりがち | なぜダメか | 代わりに |
|---|
| 書く前にチェックリストを飛ばす | 後で全部書き直すコストが大きい | Phase 1 を必ず通す |
| 「現在は」と書いてから言い換えを忘れる | hook で検知されるので開発体験が悪い | 書く瞬間に「事実宣言」に置き換える |
| 既存 doc と同じ情報を別の場所に書く | SSOT 違反、ズレが発生する | grep で確認、参照に切り替え |
| 1 段落に複数の主張を詰め込む | 流し読みできない | 1 文 1 主張、複数なら分割 |
| 専門用語を説明なしに使う | 新メンバーが脱落する | 初出で説明 or リンク |
| 「TODO: 2026 年 X 月までに」と書く | 期日は陳腐化する | issue にして条件付き寿命を書く |
