@k2works/claude-code-booster 4.15.0 → 5.0.0

package/lib/assets/.claude/skills/closing-iteration/SKILL.md

@@ -112,6 +112,20 @@ KPT（Keep / Problem / Try）で振り返り、`docs/development/retrospective-N
 - `mkdocs.yml`: ふりかえり・完了報告書・新規レビュー・新規 ADR・マニュアルの新規章をナビゲーションに追加
 - 追加行のインデントが既存ナビと一致しているか確認する
 
+### ステップ 7.5: OKF 適用（`apply-okf`）
+
+`docs/` が OKF バンドルなら、クローズで生まれた・更新された文書に規約を適用する。クローズは 1 イテレーションで最も多くの文書が動く局面（計画の実績更新・ふりかえり・報告書・レビューレポート・ADR・マニュアル）なので、`--changed` でまとめて掛ける。
+
+```bash
+python .claude/skills/apply-okf/scripts/okf_apply.py apply docs --changed --by <agent>
+gulp okf:check
+```
+
+- `retrospective-N.md`・`iteration_report-N.md`・レビューレポートは新規 → `draft` で登録。ユーザーが報告書を承認したら `verify --by human:<id>`
+- `iteration_plan-N.md` は実績で本文が変わるので `generated` が更新される。計画自体は `stable` のまま残す（後継は報告書であり、計画は廃止ではない）
+- 置き換えた ADR や旧手順があれば `deprecate --replaced-by` で後継に繋ぐ
+- `gulp okf:check` が ERROR 0 であることを確認してからコミットする
+
 ### （任意）ステップ 8: ジャーナル（`creating-journal`）
 
 長いセッションや区切りとして、判断・詰まり・学びを `docs/journal/YYYYMMDD.md` に残すと、コミットログに載らない意思決定の経緯を追跡できる。
@@ -130,6 +144,7 @@ KPT（Keep / Problem / Try）で振り返り、`docs/development/retrospective-N
 - [ ] GitHub Issue クローズ・Project Status 更新
 - [ ] **ユーザーマニュアルが実装と一致**（UI 変更ありなら本文・キャプチャを更新／変更なしならその旨を報告書に記録）
 - [ ] `docs/index.md` / `docs/development/index.md` / `mkdocs.yml` 同期
+- [ ] OKF バンドルなら `apply-okf` を変更分に適用・報告書承認後に `verify`・`gulp okf:check` ERROR 0
 - [ ] 各ステップの成果を意味のある単位でコミット（`git-commit`）
 
 ## コミットの区切り
@@ -156,5 +171,6 @@ KPT（Keep / Problem / Try）で振り返り、`docs/development/retrospective-N
 - `syncing-github-project` — GitHub 同期（ステップ 6）
 - `creating-manual` — ユーザーマニュアルの更新・画面キャプチャ再生成（ステップ 6.5）
 - `operating-docs` — ドキュメントインデックス更新・Lint（ステップ 7）
+- `apply-okf` — クローズで動いた文書への OKF 規約適用（ステップ 7.5）
 - `creating-journal` — セッション記録（任意ステップ 8）
 - `git-commit` — 各ステップ成果のコミット

package/lib/assets/.claude/skills/creating-adr/SKILL.md

@@ -79,12 +79,14 @@ ADR の価値は「決定そのもの」ではなく「なぜその決定に至
 1. `docs/adr/` ディレクトリ内の既存 ADR の最大番号を確認する
 2. 次の連番でテンプレートに基づいて ADR を作成する
 3. `docs/index.md` と `mkdocs.yml` を更新する
+4. `apply-okf` スキルで OKF バンドルに登録する（`docs/` が OKF バンドルの場合）。ADR 本文を自分が書いたので `--by` はエージェント、`status` は未レビューの `draft` になる。置換した旧 ADR があれば `deprecate --replaced-by adr/NNN-new.md` で `deprecated` にする
 
 ### 既存設計からの ADR 抽出
 
 1. アーキテクチャ設計ドキュメントを読み込む
 2. 主要な技術的意思決定を識別する
 3. 各決定を ADR として記録する
+4. 記録した ADR をまとめて `apply-okf` に掛ける（`apply docs --changed --by <agent>`）
 
 ## 途中から再開・更新
 
@@ -105,9 +107,11 @@ ADR の価値は「決定そのもの」ではなく「なぜその決定に至
 - 配置場所は必ず `docs/adr/`。新規作成時は `docs/index.md` と `mkdocs.yml` も更新する
 - ユーザーの指示があるまでコミットしない
 - コンテキストの明確化・代替案の記録・影響の両面記載・コンプライアンス項目を必ず含める
+- ADR 本文の「ステータス」と OKF の `status` は別物。本文のステータス（提案中 / 承認済み / 廃止 / 置換）は意思決定の状態、フロントマターの `status`（draft / stable / deprecated）は文書の消費可否。承認されたら `apply-okf` の `verify --by human:<id>` で `stable` に昇格させ、置換・廃止されたら `deprecate` で `deprecated` にする
 
 ## 関連スキル
 
 - `analyzing-architecture` — アーキテクチャ設計（ADR の主な発生源）
 - `analyzing-tech-stack` — 技術スタック選定（ADR として記録すべき決定）
+- `apply-okf` — 作成・承認・置換した ADR を OKF バンドルに反映
 - `git-commit` — ADR 作成後のコミット

package/lib/assets/.claude/skills/creating-journal/SKILL.md

@@ -82,7 +82,17 @@ description: その日の Skill 実行と意思決定を物語形式で `docs/jo
 
 このセッション中のコミットを `git log --oneline` で抽出し、テーブル化する。フェーズ別に分けるとさらに読みやすい。
 
-### 6. コミット
+### 6. OKF バンドルに登録
+
+`docs/` が OKF バンドル（ルート `index.md` に `okf_version` がある）なら、`apply-okf` スキルでジャーナルにフロントマターを付ける。
+
+```bash
+python .claude/skills/apply-okf/scripts/okf_apply.py apply docs docs/journal/<today>.md --by <agent>
+```
+
+ジャーナルは本文をエージェントが書くので `--by` は `claude-code/<model>` のようなエージェント形式。`type` は `journal/` から `Journal` と推定される。追記の場合も本文が変わるので `generated.at` が更新される（これが「最後に書いた日時」を正しく表す）。`journal/index.md` へのエントリ追加と `log.md` への記録はスクリプトが行う。
+
+### 7. コミット
 
 ```text
 docs(journal): YYYY-MM-DD のセッション記録を追加
@@ -126,4 +136,5 @@ docs(journal): YYYY-MM-DD のジャーナルに <セクション名> を追記
 - `creating-iteration-report` — イテレーション完了時のフォーマル報告書 (ジャーナルとは別)
 - `creating-release-report` — リリース完了時のフォーマル報告書
 - `tracking-progress` — 進捗の定量分析
+- `apply-okf` — ジャーナルへの OKF フロントマター付与と `journal/index.md`・`log.md` 更新
 - `operating-docs` — ジャーナル追加後のインデックス更新 (`--update` で `docs/index.md` 同期)

package/lib/assets/.claude/skills/creating-manual/SKILL.md

@@ -1,199 +1,199 @@
----
-name: creating-manual
-description: ユーザーマニュアル（docs/manual）の章・節の執筆、UI 変更への追従、E2E ツールによる画面キャプチャの再生成、HTML 公開までを支援する。「マニュアルを書きたい」「操作手順書を作成したい」「ユーザーマニュアルに章を追加したい」「マニュアルのキャプチャを撮り直したい」「画面が変わったのでマニュアルを更新したい」「マニュアルのスクリーンショットが古い」「操作説明を追加して」「使い方のドキュメントを整備したい」といった場面で必ず発動する。新機能の実装が終わってエンドユーザー向けの説明が要るとき、UI を変更したとき、リリース前にマニュアルの整合を確認するときにも積極的に使うこと。マニュアルは業務担当者が日次業務を完結させるための唯一の手引きなので、書式と画面キャプチャを実装と一致させ続けることが価値の source になる。特定の言語・フレームワークに依存しない汎用スキルであり、画面の実装パス・E2E ツール・コマンドは対象プロジェクトの実構成に合わせて解決する。
----
-
-# ユーザーマニュアル作成
-
-`docs/manual/` のユーザーマニュアルを執筆・更新する。読者は業務担当者であり、開発者ではない。
-
-このマニュアルの価値は網羅性ではなく **「画面の前に座った担当者がその場で手を動かせること」** にある。だから節の構成は「何ができるか → どこを開くか → 何が表示されるか → どう操作するか → 気をつけること」の順に固定する。この順序は読者が実際に迷う順序であり、崩すと読者は自分の状況に対応する記述を探せなくなる。
-
-本スキルは特定の言語・フレームワーク・E2E ツールに依存しない。画面実装のディレクトリ・キャプチャ生成の spec/設定・ビルドコマンドは、対象プロジェクトの実構成を確認して当てはめる（憶測で書かない）。
-
-## 全体構成
-
-```text
-docs/manual/
-├── index.md                 # 構成・執筆テンプレート・キャプチャ方針（マニュアルのメタ文書）
-├── 00-はじめに.md            # 読み方・表記規約・動作環境
-├── 01-業務フロー.md          # 業務フロー全体像（各章への入口）
-├── 02-*.md 〜 NN-*.md        # 画面別の操作章
-├── 用語集.md                 # 付録 A
-├── 付録B-トラブルシューティング.md  # 付録 B（Q&A 形式）
-└── assets/*.png             # 画面キャプチャ（E2E ツールが自動生成）
-```
-
-章はアプリケーションのメニュー構成に沿って並べる。章番号は画面の並び順であって業務の順序ではない。業務の順序は業務フローの章が担い、各章はそこから参照される。
-
-既存マニュアルがある場合は `docs/manual/index.md` が一次情報。本スキルの記述と食い違うときは `index.md` を正とし、必要なら `index.md` 側を更新してから執筆する。
-
-## 節の執筆テンプレート
-
-画面・タブごとに 1 節を立て、次の構成で書く。
-
-```markdown
-## <章.節> <画面・機能名>
-
-### この画面でできること
-
-- （業務上の目的を 1〜3 行。「何のためにこの画面を開くか」を書く）
-
-### 画面の開き方
-
-- メニュー「<トップ>」→ タブ「<タブ名>」（URL: `/xxx?tab=yyy`）
-
-### 画面の説明
-
-![<画面名>](assets/<章番号>-<slug>.png)
-
-| # | 項目 | 説明 |
-|---|------|------|
-| ① | <UI 要素> | <役割> |
-
-### 操作手順
-
-1. （番号付き。クリック対象は「」で囲む）
-
-### 注意・補足
-
-- （業務ルール上の注意、エラー時の対処、関連画面へのリンク）
-```
-
-節が長くなるときは「操作手順」の後に `### <具体的な作業名>` の小見出しを足してよい（例: 「CSV でまとめて登録する」）。テンプレートを壊すのではなく、テンプレートの中に足す。
-
-### 章の冒頭
-
-各章はいきなり節に入らず、次を置く。読者が「この章は自分の業務のどこか」を判断できるようにするため。
-
-1. 章で何をする画面かを 1〜2 文
-2. 対応する業務フローへのリンク（`本章は [WF-1（...）](01-業務フロー.md#...) の...工程に対応します。`）
-3. 「画面の開き方」（メニューと URL）
-4. タブ一覧の表（タブ / 役割 / 節へのリンク）
-5. 隣接画面との境界の補足（「〜そのものは別画面で確認します」など）
-
-タブ表の「節」列は章内アンカー（`[7.1](#71-出荷予定)`）にする。読者はタブ名で探すので、タブ表が章の目次を兼ねる。
-
-## 表記規約
-
-`00-はじめに.md` の表記規約に従う。実装ではなく読者の語彙で書くのが要点。
-
-| 規約 | 例 |
-|------|-----|
-| 文体はですます調 | 「〜します」「〜してください」 |
-| ボタン・タブ・入力項目・選択肢は「」で囲む | 「検索」をクリックします |
-| 画面の場所はメニュー → タブの順 | メニュー「受注」→ タブ「入金確認」 |
-| 画面項目には丸数字を振り、表で対応させる | ①②③…（キャプチャ側の赤枠と対応） |
-| ステータスは画面の表示名で書く | 「引当済」（`ALLOCATED` ではなく） |
-| 専門用語は初出で簡潔に補足し用語集へリンク | [用語集 §1](用語集.md#1-業務用語) |
-
-避けること:
-
-- テーブル名・カラム名・API パス・クラス名を本文に出す（読者は画面しか見ない）
-- 「〜が可能です」の多用（「〜できます」で足りる）
-- 実装都合の説明（「非同期で処理されるため」→「反映まで少し時間がかかります」）
-
-業務ルールに関わる注意は本文に混ぜず「注意・補足」に集める。読者が操作中に読むのは手順、つまずいてから読むのが注意だから。根拠がある注意には該当 ADR や設計ドキュメントへリンクを張る。
-
-## 画面キャプチャ
-
-キャプチャは **E2E ツール（Playwright / Cypress 等）で自動生成する。手作業で PNG を置いてはいけない** — 次回の再生成で上書きされ、UI 変更のたびに撮り漏れが出る。
-
-対象プロジェクトの実構成を確認し、次の要素を特定してから作業する。無ければ最初に用意する。
-
-| 項目 | 内容 |
-|------|------|
-| 生成 spec | キャプチャ専用のテストファイル（例: `e2e/manual/manual-screenshots.spec.ts`） |
-| 設定 | キャプチャ専用の設定ファイル（例: `playwright.manual.config.ts`） |
-| 実行コマンド | 専用の npm script（例: `npm run screenshots:manual`）。出力先は `docs/manual/assets/` |
-| 配信 | **本番相当ビルド**をローカル配信（例: ビルド成果物を preview サーバで配信） |
-| データ | spec 内の API モック（バックエンド不要で決定的に撮れる） |
-| 命名 | `<章番号>-<英字スラッグ>[-連番].png`（例: `07-scheduled.png` / `04-payment-confirm-01.png`） |
-
-### 本番相当ビルドで撮る理由
-
-多くのアプリはビルドモードで見た目を変える（開発用のテーマ色・「非本番環境」バッジなど）。開発サーバで撮ると利用者が実際に見る画面と食い違う。一方で **本番環境そのものへは接続しない** — マニュアルは Git 管理下で公開されるため、実在の顧客名・住所・電話番号がリポジトリに残るのを避ける。**見た目は本番ビルド、データはモック**で揃えるのが原則。
-
-この理由から、既定の E2E テスト実行からはキャプチャ spec を除外する（Playwright なら `testIgnore`）。開発サーバで動かすと非本番テーマの PNG で上書きしてしまうため、除外を外さないこと。
-
-### 新しい画面のキャプチャを足す
-
-キャプチャ spec にテストを追加する。既存テストが雛形になる。
-
-1. 必要な API をモックする（モックしないと取得エラーの赤帯が写り込む）
-2. 既存ヘルパーでログインする
-3. 目的の画面へ遷移する
-4. 主要要素の表示を待つ（待たずに撮ると描画途中が写る）
-5. `<章番号>-<slug>.png` で撮影する
-
-テスト名は `'<ファイル名>（<画面の日本語名>）'` の形にそろえる（例: `'04-orders-list（受注一覧）'`）。失敗時にどのキャプチャが壊れたかが分かる。
-
-### データの方針
-
-- 実在の顧客名・住所・電話番号・メールアドレスは載せない。ダミー値を使う
-- 代表的な 1 件以上のデータが表示された状態で撮る。空状態を説明する節では空状態も撮る
-- フィーチャートグルで制御している機能は、本番既定（多くは無効）の状態で撮影される。トグル配下の機能を載せる節は、本番で有効化してから撮影・記載する
-
-## 進め方
-
-### 新しい章・節を書く
-
-1. **対象画面を実際に確認する。** 画面の実装コードとユーザーストーリーを読み、タブ構成・項目・操作の流れを把握する。推測で書くと読者がその場で詰まる
-2. **どの業務フローのどのステップかを決める。** 業務フローの章から参照される位置づけがないと、読者はその画面をいつ使うのか分からない
-3. **節をテンプレートに沿って書く。** 章の冒頭（概要・業務フローリンク・タブ表）も忘れずに置く
-4. **キャプチャを spec に足して生成する**（前節の手順）
-5. **索引を更新する** — `docs/manual/index.md` の章表、`00-はじめに.md` の全体構成表、`mkdocs.yml` の nav（`manual/` 配下）。章を足したのに索引が古いと、読者はそのページに辿り着けない
-6. **`operating-docs` の Markdown Lint を通す**
-
-### UI 変更に追従する
-
-1. 変更された画面を特定し、該当節の「画面の説明」の項目表・「操作手順」を実装と突き合わせる
-2. キャプチャ生成コマンドで PNG を再生成する
-3. 生成された PNG と本文の丸数字・項目表がずれていないか確認する（項目が増減していれば表も直す）
-4. 画面が増減した場合はタブ表と `index.md` の章表も直す
-
-### 公開する
-
-```bash
-npx gulp manual:build   # docs/manual → apps/manual へ HTML 出力
-```
-
-`ops/scripts/manual.js` が Markdown を HTML へ変換する（PlantUML はサーバレンダリング、`.md` リンクは `.html` へ書き換え）。サイトタイトル・著作権表示・ポータルへの戻りリンクは `.env` の `MANUAL_TITLE` / `MANUAL_COPYRIGHT` / `MANUAL_PORTAL_URL` で設定する。
-
-マニュアルは `mkdocs` の設計ドキュメントサイトにも載るため、章を増減したら `mkdocs.yml` の nav も合わせる。静的サイトへのデプロイは対象プロジェクトのデプロイタスクが担う。
-
-## トラブルシューティング章（付録 B）
-
-付録 B だけは操作章と型が違う。症状から引く Q&A 形式で書く。
-
-- 見出しは `### Q<節>-<連番>. <症状を読者の言葉で>`（例: `Q1-1. ログインできない（「ログイン ID またはパスワードが正しくありません。」）`）
-- 画面に出るメッセージはそのまま引用する。読者はメッセージで検索する
-- 「確認すること / 対処」の 2 列表が使いやすい
-- **仕様であって不具合ではないもの**は、そう明記する。これが分からないと問い合わせが増える
-- エラーメッセージ早見表の節を維持し、新しいメッセージを追加したら載せる
-
-## 注意事項
-
-- 執筆前に既存章を 1 つ通読する。テンプレートの解釈が揃う（短い章ほど型が見やすい）
-- キャプチャの手動配置は禁止。必ず spec 経由で生成する
-- 個人情報・トークン・社内 URL を本文にもキャプチャにも残さない
-- 章を追加・削除したら `index.md` / `00-はじめに.md` / `mkdocs.yml` の 3 箇所を必ず揃える
-- ユーザーの指示があるまでコミットしない
-
-## 関連ドキュメント
-
-存在するものを使う。無いものは前提にしない。
-
-- `docs/manual/index.md` — 章構成・執筆テンプレート・キャプチャ方針の一次情報
-- ユーザーストーリー（例: `docs/requirements/user_story.md`）— 各章の機能要件の出典
-- UI 設計（例: `docs/design/ui_design.md`）— 画面仕様
-- 受け入れテスト計画（例: `docs/development/acceptance_test_plan.md`）— 業務フローとの対応
-
-## 関連スキル
-
-- `operating-docs` — ドキュメント管理・Markdown Lint
-- `analyzing-ui-design` — 画面設計（マニュアルの記述対象）
-- `developing-uiux-review` — UI/UX レビュー（マニュアルで説明しにくい画面は設計を疑う）
-- `opening-iteration` — イテレーション計画へのマニュアル更新タスクの計上（ステップ 2）
-- `closing-iteration` — クローズ時のマニュアル更新（ステップ 6.5）
-- `git-commit` — マニュアル更新後のコミット
+---
+name: creating-manual
+description: ユーザーマニュアル（docs/manual）の章・節の執筆、UI 変更への追従、E2E ツールによる画面キャプチャの再生成、HTML 公開までを支援する。「マニュアルを書きたい」「操作手順書を作成したい」「ユーザーマニュアルに章を追加したい」「マニュアルのキャプチャを撮り直したい」「画面が変わったのでマニュアルを更新したい」「マニュアルのスクリーンショットが古い」「操作説明を追加して」「使い方のドキュメントを整備したい」といった場面で必ず発動する。新機能の実装が終わってエンドユーザー向けの説明が要るとき、UI を変更したとき、リリース前にマニュアルの整合を確認するときにも積極的に使うこと。マニュアルは業務担当者が日次業務を完結させるための唯一の手引きなので、書式と画面キャプチャを実装と一致させ続けることが価値の source になる。特定の言語・フレームワークに依存しない汎用スキルであり、画面の実装パス・E2E ツール・コマンドは対象プロジェクトの実構成に合わせて解決する。
+---
+
+# ユーザーマニュアル作成
+
+`docs/manual/` のユーザーマニュアルを執筆・更新する。読者は業務担当者であり、開発者ではない。
+
+このマニュアルの価値は網羅性ではなく **「画面の前に座った担当者がその場で手を動かせること」** にある。だから節の構成は「何ができるか → どこを開くか → 何が表示されるか → どう操作するか → 気をつけること」の順に固定する。この順序は読者が実際に迷う順序であり、崩すと読者は自分の状況に対応する記述を探せなくなる。
+
+本スキルは特定の言語・フレームワーク・E2E ツールに依存しない。画面実装のディレクトリ・キャプチャ生成の spec/設定・ビルドコマンドは、対象プロジェクトの実構成を確認して当てはめる（憶測で書かない）。
+
+## 全体構成
+
+```text
+docs/manual/
+├── index.md                 # 構成・執筆テンプレート・キャプチャ方針（マニュアルのメタ文書）
+├── 00-はじめに.md            # 読み方・表記規約・動作環境
+├── 01-業務フロー.md          # 業務フロー全体像（各章への入口）
+├── 02-*.md 〜 NN-*.md        # 画面別の操作章
+├── 用語集.md                 # 付録 A
+├── 付録B-トラブルシューティング.md  # 付録 B（Q&A 形式）
+└── assets/*.png             # 画面キャプチャ（E2E ツールが自動生成）
+```
+
+章はアプリケーションのメニュー構成に沿って並べる。章番号は画面の並び順であって業務の順序ではない。業務の順序は業務フローの章が担い、各章はそこから参照される。
+
+既存マニュアルがある場合は `docs/manual/index.md` が一次情報。本スキルの記述と食い違うときは `index.md` を正とし、必要なら `index.md` 側を更新してから執筆する。
+
+## 節の執筆テンプレート
+
+画面・タブごとに 1 節を立て、次の構成で書く。
+
+```markdown
+## <章.節> <画面・機能名>
+
+### この画面でできること
+
+- （業務上の目的を 1〜3 行。「何のためにこの画面を開くか」を書く）
+
+### 画面の開き方
+
+- メニュー「<トップ>」→ タブ「<タブ名>」（URL: `/xxx?tab=yyy`）
+
+### 画面の説明
+
+![<画面名>](assets/<章番号>-<slug>.png)
+
+| # | 項目 | 説明 |
+|---|------|------|
+| ① | <UI 要素> | <役割> |
+
+### 操作手順
+
+1. （番号付き。クリック対象は「」で囲む）
+
+### 注意・補足
+
+- （業務ルール上の注意、エラー時の対処、関連画面へのリンク）
+```
+
+節が長くなるときは「操作手順」の後に `### <具体的な作業名>` の小見出しを足してよい（例: 「CSV でまとめて登録する」）。テンプレートを壊すのではなく、テンプレートの中に足す。
+
+### 章の冒頭
+
+各章はいきなり節に入らず、次を置く。読者が「この章は自分の業務のどこか」を判断できるようにするため。
+
+1. 章で何をする画面かを 1〜2 文
+2. 対応する業務フローへのリンク（`本章は [WF-1（...）](01-業務フロー.md#...) の...工程に対応します。`）
+3. 「画面の開き方」（メニューと URL）
+4. タブ一覧の表（タブ / 役割 / 節へのリンク）
+5. 隣接画面との境界の補足（「〜そのものは別画面で確認します」など）
+
+タブ表の「節」列は章内アンカー（`[7.1](#71-出荷予定)`）にする。読者はタブ名で探すので、タブ表が章の目次を兼ねる。
+
+## 表記規約
+
+`00-はじめに.md` の表記規約に従う。実装ではなく読者の語彙で書くのが要点。
+
+| 規約 | 例 |
+|------|-----|
+| 文体はですます調 | 「〜します」「〜してください」 |
+| ボタン・タブ・入力項目・選択肢は「」で囲む | 「検索」をクリックします |
+| 画面の場所はメニュー → タブの順 | メニュー「受注」→ タブ「入金確認」 |
+| 画面項目には丸数字を振り、表で対応させる | ①②③…（キャプチャ側の赤枠と対応） |
+| ステータスは画面の表示名で書く | 「引当済」（`ALLOCATED` ではなく） |
+| 専門用語は初出で簡潔に補足し用語集へリンク | [用語集 §1](用語集.md#1-業務用語) |
+
+避けること:
+
+- テーブル名・カラム名・API パス・クラス名を本文に出す（読者は画面しか見ない）
+- 「〜が可能です」の多用（「〜できます」で足りる）
+- 実装都合の説明（「非同期で処理されるため」→「反映まで少し時間がかかります」）
+
+業務ルールに関わる注意は本文に混ぜず「注意・補足」に集める。読者が操作中に読むのは手順、つまずいてから読むのが注意だから。根拠がある注意には該当 ADR や設計ドキュメントへリンクを張る。
+
+## 画面キャプチャ
+
+キャプチャは **E2E ツール（Playwright / Cypress 等）で自動生成する。手作業で PNG を置いてはいけない** — 次回の再生成で上書きされ、UI 変更のたびに撮り漏れが出る。
+
+対象プロジェクトの実構成を確認し、次の要素を特定してから作業する。無ければ最初に用意する。
+
+| 項目 | 内容 |
+|------|------|
+| 生成 spec | キャプチャ専用のテストファイル（例: `e2e/manual/manual-screenshots.spec.ts`） |
+| 設定 | キャプチャ専用の設定ファイル（例: `playwright.manual.config.ts`） |
+| 実行コマンド | 専用の npm script（例: `npm run screenshots:manual`）。出力先は `docs/manual/assets/` |
+| 配信 | **本番相当ビルド**をローカル配信（例: ビルド成果物を preview サーバで配信） |
+| データ | spec 内の API モック（バックエンド不要で決定的に撮れる） |
+| 命名 | `<章番号>-<英字スラッグ>[-連番].png`（例: `07-scheduled.png` / `04-payment-confirm-01.png`） |
+
+### 本番相当ビルドで撮る理由
+
+多くのアプリはビルドモードで見た目を変える（開発用のテーマ色・「非本番環境」バッジなど）。開発サーバで撮ると利用者が実際に見る画面と食い違う。一方で **本番環境そのものへは接続しない** — マニュアルは Git 管理下で公開されるため、実在の顧客名・住所・電話番号がリポジトリに残るのを避ける。**見た目は本番ビルド、データはモック**で揃えるのが原則。
+
+この理由から、既定の E2E テスト実行からはキャプチャ spec を除外する（Playwright なら `testIgnore`）。開発サーバで動かすと非本番テーマの PNG で上書きしてしまうため、除外を外さないこと。
+
+### 新しい画面のキャプチャを足す
+
+キャプチャ spec にテストを追加する。既存テストが雛形になる。
+
+1. 必要な API をモックする（モックしないと取得エラーの赤帯が写り込む）
+2. 既存ヘルパーでログインする
+3. 目的の画面へ遷移する
+4. 主要要素の表示を待つ（待たずに撮ると描画途中が写る）
+5. `<章番号>-<slug>.png` で撮影する
+
+テスト名は `'<ファイル名>（<画面の日本語名>）'` の形にそろえる（例: `'04-orders-list（受注一覧）'`）。失敗時にどのキャプチャが壊れたかが分かる。
+
+### データの方針
+
+- 実在の顧客名・住所・電話番号・メールアドレスは載せない。ダミー値を使う
+- 代表的な 1 件以上のデータが表示された状態で撮る。空状態を説明する節では空状態も撮る
+- フィーチャートグルで制御している機能は、本番既定（多くは無効）の状態で撮影される。トグル配下の機能を載せる節は、本番で有効化してから撮影・記載する
+
+## 進め方
+
+### 新しい章・節を書く
+
+1. **対象画面を実際に確認する。** 画面の実装コードとユーザーストーリーを読み、タブ構成・項目・操作の流れを把握する。推測で書くと読者がその場で詰まる
+2. **どの業務フローのどのステップかを決める。** 業務フローの章から参照される位置づけがないと、読者はその画面をいつ使うのか分からない
+3. **節をテンプレートに沿って書く。** 章の冒頭（概要・業務フローリンク・タブ表）も忘れずに置く
+4. **キャプチャを spec に足して生成する**（前節の手順）
+5. **索引を更新する** — `docs/manual/index.md` の章表、`00-はじめに.md` の全体構成表、`mkdocs.yml` の nav（`manual/` 配下）。章を足したのに索引が古いと、読者はそのページに辿り着けない
+6. **`operating-docs` の Markdown Lint を通す**
+
+### UI 変更に追従する
+
+1. 変更された画面を特定し、該当節の「画面の説明」の項目表・「操作手順」を実装と突き合わせる
+2. キャプチャ生成コマンドで PNG を再生成する
+3. 生成された PNG と本文の丸数字・項目表がずれていないか確認する（項目が増減していれば表も直す）
+4. 画面が増減した場合はタブ表と `index.md` の章表も直す
+
+### 公開する
+
+```bash
+npx gulp manual:build   # docs/manual を HTML へ変換して静的サイトへ出力
+```
+
+`ops/scripts/manual.js` が Markdown を HTML へ変換する（PlantUML はサーバレンダリング、`.md` リンクは `.html` へ書き換え）。**出力先と設定できる項目はプロジェクトによって違う**ので、`ops/scripts/manual.js` の定数と `process.env` の参照を実際に確認してから使う。
+
+マニュアルは `mkdocs` の設計ドキュメントサイトにも載るため、章を増減したら `mkdocs.yml` の nav も合わせる。静的サイトへのデプロイは対象プロジェクトのデプロイタスクが担う。
+
+## トラブルシューティング章（付録 B）
+
+付録 B だけは操作章と型が違う。症状から引く Q&A 形式で書く。
+
+- 見出しは `### Q<節>-<連番>. <症状を読者の言葉で>`（例: `Q1-1. ログインできない（「ログイン ID またはパスワードが正しくありません。」）`）
+- 画面に出るメッセージはそのまま引用する。読者はメッセージで検索する
+- 「確認すること / 対処」の 2 列表が使いやすい
+- **仕様であって不具合ではないもの**は、そう明記する。これが分からないと問い合わせが増える
+- エラーメッセージ早見表の節を維持し、新しいメッセージを追加したら載せる
+
+## 注意事項
+
+- 執筆前に既存章を 1 つ通読する。テンプレートの解釈が揃う（短い章ほど型が見やすい）
+- キャプチャの手動配置は禁止。必ず spec 経由で生成する
+- 個人情報・トークン・社内 URL を本文にもキャプチャにも残さない
+- 章を追加・削除したら `index.md` / `00-はじめに.md` / `mkdocs.yml` の 3 箇所を必ず揃える
+- ユーザーの指示があるまでコミットしない
+
+## 関連ドキュメント
+
+存在するものを使う。無いものは前提にしない。
+
+- `docs/manual/index.md` — 章構成・執筆テンプレート・キャプチャ方針の一次情報
+- ユーザーストーリー（例: `docs/requirements/user_story.md`）— 各章の機能要件の出典
+- UI 設計（例: `docs/design/ui_design.md`）— 画面仕様
+- 受け入れテスト計画（例: `docs/development/acceptance_test_plan.md`）— 業務フローとの対応
+
+## 関連スキル
+
+- `operating-docs` — ドキュメント管理・Markdown Lint
+- `analyzing-ui-design` — 画面設計（マニュアルの記述対象）
+- `developing-uiux-review` — UI/UX レビュー（マニュアルで説明しにくい画面は設計を疑う）
+- `opening-iteration` — イテレーション計画へのマニュアル更新タスクの計上（ステップ 2）
+- `closing-iteration` — クローズ時のマニュアル更新（ステップ 6.5）
+- `git-commit` — マニュアル更新後のコミット