| name | anytime-doc-authoring |
| effort | low |
| description | /Shared/anytime-markdown-docs 配下のドキュメントを新規作成・執筆する時に、type（spec/tech/test/manual/proposal/plan/review/report）ごとの記載内容（何を書くか）・フォルダ構成・索引 index.[lang].md の自動生成運用を定義する。設計書（spec）の書き方・component spec の 2 ファイル分離・E2E シナリオ表・技術解説記事（tech。「技術記事を書いて」「ブログ記事を作成」「解説記事を書いて」等）の構成テンプレート・執筆ガイドライン・文体・生成ワークフロー・試験設計書（「試験設計書」「テスト設計書」「テストケースを設計」「テスト観点で洗い出し」「テスト計画」「QA 設計」等。7 ペルソナ観点・技法・自動化判定）・プランファイルの「変更対象ファイル」節・索引再生成が必要な時に使用する。構文・フロントマター・整形は anytime-markdown-output、既存設計書の読み方・辿り方は anytime-spec-lookup を使う。 |
ドキュメント記載内容ガイド（anytime-doc-authoring）
更新日: 2026-07-11
/Shared/anytime-markdown-docs/ 配下のドキュメントについて、type ごとに「何を書くか」（記載内容・構成・運用）を定義する。
0. スキルの分担
| スキル | 担当 |
|---|
| anytime-doc-authoring（本スキル） | 何を書くか（type 別の記載内容・フォルダ構成・索引運用） |
anytime-markdown-output | どう書くか（GFM 構文・フロントマター仕様・整形・図表原則） |
anytime-spec-lookup | どう読むか（索引 → frontmatter → 型付き related の progressive disclosure） |
1. 共通規則
1.1. フォルダ構成と命名
- 共通ドキュメント（設計書・テスト項目書・マニュアル等）:
[topic]/ フォルダを作成し [topic].[lang].md（日英両方）を出力する。画像は [topic]/images/。
- 都度作成ドキュメント（plan・review・report）:
[YYYYMMDD]-[topic].[lang].md — 指示がなければ日本語のみ。
lang は ja / en。type と出力先フォルダの対応は anytime-markdown-output §2.2。分類が不明な場合はユーザーに確認する。
1.2. 予約索引 index.[lang].md（各フォルダ必須・OKF 段階開示）
type フォルダおよびその全サブフォルダの直下に索引 index.[lang].md を置く（OKF の index.md 入れ子構造に相当）。
-
各索引は (1) 直下サブフォルダの索引へのリンク（件数つき）と (2) 直下ドキュメントの一覧・概要を載せ、ルートの <type>/index.[lang].md がサブフォルダ目次になる。
-
索引は frontmatter（title / category / excerpt / 型付き related）から scripts/gen-spec-index.mjs で自動生成し手書きしない（生成物のため手で編集しない）。
-
ドキュメントを追加・更新・改名・削除したら同フォルダの索引が必ず変わるため再生成を必須とする（title / excerpt 変更でも索引表示がずれるため更新時も対象）。
-
対象 type に応じて再生成コマンドを実行する（リポジトリルートの npm scripts）:
| type | コマンド |
|---|
| spec | npm run spec:index |
| tech | npm run tech:index |
| proposal | npm run proposal:index |
| review | npm run review:index |
1.3. 共通の書き方原則
- 結論ファースト: ファイル冒頭・各セクション冒頭に要点を先に置く。
- 1 ファイル 1 トピック・目安 400 行以下: 超える場合は
## 単位で分割し related と本文リンクで結ぶ。
- 既存コンセプトはインラインリンクで結ぶ: 他の設計書・テーブル・パッケージ等に言及する際はルート相対リンクで接続する（note-graph のリンクグラフ形成）。
- frontmatter の
related は型付き（references / depends-on / implements / part-of / supersedes / refines。語彙は spec/33.graph/03.graph-viewer/note-relations.ja.md）。
2. type 別の記載内容
2.1. spec（設計書）
機能仕様・アーキテクチャ設計・データモデル定義等。spec/<NN>.<topic>/ の番号付きフォルダに配置する。
- 機能仕様＝外部仕様（black-box）で書く。実装仕様（white-box）を書かない（詳細は §3.1）。
type: "spec" には c4Scope（C4 モデル要素 ID 配列）を付与する（仕様は anytime-markdown-output §2.3）。- 設計判断を含む場合はフロントマターに
status（draft / accepted / implemented 等）を持たせ、実装完了時に更新する。
- パッケージ設計書（component spec）は §3 のルールに従う。
2.2. test（テスト項目書・試験設計書）
ユニット・E2E テストのケース一覧、および試験設計書。
- E2E シナリオは機能セクションごとに 1 つの横型表（列固定:
| No | シナリオ | 前提条件 | 操作 | 期待結果 | 備考 |）。詳細は §3.4。
- 期待結果は外部から決定論的に観測できるものに限定する（内部状態を書かない）。
- 試験設計書（テスト観点の洗い出し・ケース構造化・自動/手動の区別）は §5 に従う。
2.3. proposal（提案）
改善提案・新機能提案・技術選定。**やるべきか（Why/What）**を扱い、実装手順（How)は plan に書く。
- 生成手順・テンプレート・思考法ガイドは
anytime-proposal スキルに従う。
2.4. plan（実装計画）
タスク分解・変更対象・検証コマンドの定義。承認後に実装する。
-
フロントマターに clarity（指示の明確さ 1〜100）を記載する（global CLAUDE.md「応答」）。
-
## 変更対象ファイル セクション（機械契約）: 変更予定ファイルを - + バッククォート付きパスの箇条書きで列挙する。agent-status hook（agent-status-report.mjs planned モード）がこの見出しを走査して plannedEdits を抽出するため、見出し文言・箇条書き形式を変えない。パスはワークスペースルート相対で書く。
## 変更対象ファイル
- `packages/<pkg>/src/<file>.ts`
- `packages/<pkg>/README.md`
-
検証コマンド（ビルド・テスト・型チェック）は対象 package.json の scripts / devDependencies を事前確認して実在するものだけ書く（AGENTS.md「検証コマンドの実在確認」）。
-
進捗・完了状態はプランファイル自身に記録し、完了時に更新する。
-
Codex へ委任するタスクは codex-delegation スキルの 6 点（対象/禁止範囲/完了条件/検証/中断条件/プロンプト）を記載する。
2.5. review（レビュー記録）
コードレビュー結果・設計レビュー記録。
- 指摘の書式（
### N. タイトル + 重大度/カテゴリ/対象 + 行頭 問題:/提案: マーカー）は anytime-review スキルに従う（trail memory-core ingest が機械読取する契約）。
2.6. report（レポート）
日次・週次調査、Issue 解決レポート等。Web アプリの /report ページに一覧表示される。
category / excerpt は一覧表示・OG description に使われるため必ず付与する（機械契約は anytime-markdown-output §2.1.1）。
2.7. tech / manual
- tech: 技術調査・技術解説記事。比較は表＋評価軸を明示し、出典を脚注で示す（
anytime-markdown-output 第 4 章)。解説記事の構成・執筆・文体・生成ワークフローは §4 に従う。
- manual: ユーザー向け操作ガイド。前提条件 → 手順（番号付き）→ 結果確認の順で書き、スクリーンショットには alt テキスト必須。
3. component spec（パッケージ設計書）の記載ルール
spec/<NN>.<pkg>/ 配下のパッケージ設計書は、以下のルールで記載する。雛形は spec/31.markdown-viewer/。
3.1. 機能仕様（外部仕様）で書く
実装仕様（white-box）でなく 機能仕様＝外部仕様（black-box） で書く。利用者・搭載製品から見た「何ができるか・どう振る舞うか」を記述する。
- 書く: 編集モード、各機能の操作と結果、表示設定の選択肢と意味、入出力（GFM / frontmatter）、国際化、制約・非対応（non-goals）。
- 書かない（除外）: ディレクトリ構成・ファイルツリー、拡張内部・NodeView・PluginKey、関数名／クラス名／型名（
createMarkdownMinimap 等）、レイヤー図・依存一覧・ビルド／移管の内部事情、コードシンボル単位の API 表。
- 機能名は一般語で書き、内部識別子に依存しない。
3.2. 機能説明と E2E シナリオを別ファイルに分離
UI／挙動を持つパッケージは、同一フォルダに 2 ファイルを並置する。
| ファイル | type | category | 内容 |
|---|
<pkg>.ja.md | spec | <pkg> 等 | 機能説明（各機能が何をするかの説明文＋説明表） |
<pkg>-e2e.ja.md | test | e2e | E2E シナリオ表（テスト実施対象） |
- 相互リンク:
related で spec → e2e は references、e2e → spec は part-of。本文冒頭にも相互リンクを置く。
- 純ロジック lib（end-user UI なし）は シナリオを持たないため分離しない。単一 spec に「入力 → 出力／振る舞い」の外部契約（公開 API の入出力・保証）を記述する。
3.3. 機能説明（<pkg>.ja.md）の書き方
- 各機能セクションは「何をするか」の説明文を 必ず持つ（シナリオだけの節を作らない）。
- 説明表（モード一覧・設定一覧・コマンド一覧・入出力表・ツールバー表 等）は spec 側に残す。
- シナリオ表は置かない（e2e 側へ）。
3.4. E2E シナリオ（<pkg>-e2e.ja.md）の書き方
-
機能セクションごとに 1 つの横型表を置く。列は固定:
| No | シナリオ | 前提条件 | 操作 | 期待結果 | 備考 |
-
1 行＝1 シナリオ。No は 表単位で 1 始まり。
-
期待結果 は外部から決定論的に観測できるもの（画面表示・挿入される Markdown・モード遷移・保存結果 等）に限定する。内部状態は書かない。
-
既存 spec/30.markdown/test/e2e-test-list.md の用語・粒度と整合させる。
3.5. 見出し粒度の整合
- 同一見出しレベルでは項目単位を揃える。要素名（例: ツールバー）と内容種別（例: シナリオ）を同レベルに混在させない。
### シナリオ のような汎用見出しを作らない。- 単一要素のためだけの冗長な
### 見出しを作らず、本文の太字コード行等にする。
3.6. 内部相互参照
- 節への相互参照は
§N のプレーン参照で書く。](#日本語見出し) アンカーリンクはスラッグが一致せず壊れるため使わない。
3.7. frontmatter と索引
title は「 機能仕様書」「 E2E シナリオ」。updated は編集当日。type: "spec" には c4Scope を付与（anytime-markdown-output §2.3）。- 追加・更新・改名・削除のたびに同フォルダ索引を再生成する（§1.2。
npm run spec:index）。
4. 技術解説記事（tech）の記載ルール
/Shared/anytime-markdown-docs/tech/ に出力する技術解説記事の構成・執筆・文体・生成ワークフロー。読者が「自分の頭が整理された」と感じ、Web 記事としてスラスラ読める構成を目指す。機能の羅列でなく、エンジニアが実務でどう活用すべきかに焦点を当てる。生成は §4.6 のワークフロー（テーマ確認 → 情報整理 → 執筆 → 検証 → 出力）で進める。
4.1. 記事構成テンプレート
---
title: "タイトル"
date: "YYYY-MM-DD"
updated: "YYYY-MM-DD"
type: "tech"
lang: "ja"
author: "Claude Code v{VERSION} ({MODEL_ID})（編集・監修: {EDITOR_NAME}）"
skill: "anytime-doc-authoring ({SKILL_DATE})"
category: "カテゴリ名"
excerpt: "記事の要約。200文字以内。"
---
# タイトル
> **AI 生成コンテンツに関する注意事項**
>
> この記事は AI（Claude Code）によって生成されたものである。内容の正確性には注意を払っているが、以下の点に留意されたい。
>
> - 記載内容は執筆時点の情報に基づく。ソフトウェアのバージョンアップにより仕様が変更される可能性がある
> - 具体的な数値は公式ドキュメントや既知の情報に基づくが、環境や条件によって異なる場合がある
> - 最新の正確な情報は公式ドキュメントを参照すること
> - 記事中のイラストは AI が生成したものであり、概念の理解を助ける目的で挿入している
## はじめに
<!-- 課題提起 + この記事で得られること（2-3文） -->
<!-- 導入部で読者にとってのベネフィットを提示する -->
## 前提知識
<!-- 対象読者と必要な前提（箇条書き） -->
## [本文セクション 1: 概念の説明]
<!-- What: それは何か -->
## [本文セクション 2: 具体例]
<!-- How: コード例・設定例・図解で示す -->
## [本文セクション 3: 深掘り]
<!-- Why: なぜそうなるか、内部の仕組み、注意点 -->
## まとめ
<!-- 要点を3-5個の箇条書きで整理 -->
## 参考リンク
<!-- 公式ドキュメント、関連記事へのリンク -->
本文セクションの数と見出しはテーマに応じて調整する。上記は最小構成であり、必要に応じてセクションを追加する。
4.2. メタ情報の記載
テンプレート内のプレースホルダーを以下の手順で置き換える。
| プレースホルダー | 取得方法 |
|---|
{VERSION} | claude --version の出力（例: 2.1.71） |
{MODEL_ID} | 現在使用中のモデル ID（例: claude-opus-4-6） |
{EDITOR_NAME} | 編集・監修者の名前（ユーザーに確認） |
{SKILL_DATE} | 本スキル（anytime-doc-authoring）SKILL.md の最終更新日（stat -c %y で取得） |
author フィールドは「どのツール・モデルで生成されたか」「誰が編集・監修したか」を明示し、再現性と信頼性の判断材料を提供する（anytime-markdown-output の frontmatter 規約に従う）skill フィールドは、記事生成に使用したスキル名とそのバージョン（日付）を記載する- AI 生成注意事項は、読者への免責と公式情報への誘導を目的とする。イラストを含まない記事では該当行を省略する
4.3. 執筆ガイドライン
基本方針:
- PREP 法の徹底: 重要な知見は結論（Point）から書き始める
- 1文1メッセージ: 複雑な技術解説ほど、一文を短く切り、論理構造を明確にする
- 自分事化: 導入部で「開発効率が上がる」「記憶の喪失を防げる」といった読者のベネフィットを提示する
見出し:
- h1: 記事タイトル（1つのみ）
- h2: 大セクション（5-8個目安）
- h3: サブトピック（必要に応じて）
リード文:
- 1文目で読者の課題・疑問を提示する
- 2文目でこの記事が何を解決するか述べる
- 3文目で記事の構成を簡潔に示す
本文:
- 1段落は3-4文以内。長くなったら分割する
- 抽象的な説明の直後に具体例を置く
- 専門用語の初出時は簡潔に定義する
- 「つまり」「言い換えると」で要約を挟み、理解を補強する
逆引きリファレンス: コマンド一覧や API リファレンスは「やりたいこと（ユースケース）」をベースに分類し、読者が目的の情報をすぐに見つけられるようにする。
コード例:
- 動作する最小限のコードを示す
- コメントは「なぜ」を説明する（「何をしているか」はコードが語る）
- 入力と出力をセットで示す
- 言語指定を必ず付ける（```typescript 等）
- パス・環境変数はコピー＆ペースト可能な形式で記載する
図解・表:
- 文章だけで複雑になる構造・フロー・関係性は Mermaid 図を使う（
anytime-mermaid スキル）
- 図の直前に1文で図の要点を述べる
- 記憶の種類、ロード順、優先度などは比較表で一目で理解できるようにする
挿絵（PNG イラスト）: 長い文章の合間にセクションの内容を象徴する簡易イラストを挿入し、読者の疲労を軽減する。
- SVG コードを生成し、Playwright で PNG に変換して出力する（
page.locator('svg').screenshot() → images/ へ保存し相対パスで参照）
- フラットデザイン風。色数は 3-4 色、装飾は最小限。幾何学的な形状（丸、四角、矢印）の組み合わせで概念を表現する
- サイズは 400x200 程度。背景は透過または薄いグレー。影やグラデーションは使わない
- 文字は含めない（多言語対応・フォント依存を回避するため）
- 1記事に 2-3 枚を目安とし、h2 セクションの冒頭に配置する
コールアウト（補足・警告）: 重要な警告や Tips は引用ブロックで本文と区別する。
> **注意**: マネージドポリシーの CLAUDE.md は `claudeMdExcludes` で除外できない。
4.4. 文体・読みやすさ
- 漢字3割・ひらがな7割: 適度に漢字を「開く（ひらがなにする）」ことで読みやすさを確保
- 体言止めの多用を避ける: 文末は「〜する」「〜できる」「〜である」で締める
- 接続詞の適切な使用: 「つまり」「一方で」「具体的には」で論理の流れを明示する
4.5. 出力後の確認チェックリスト
ファイル保存後、以下を確認する。
4.6. 生成ワークフロー
- テーマの確認: 以下をユーザーから確認する（明示されていない場合のみ質問）。
- テーマ（何について書くか）/ 対象読者（初心者・中級者・上級者。デフォルト: 中級者）/ 想定文字数（短め 2000 字・標準 4000 字・長め 6000 字。デフォルト: 標準）
- 情報の階層化: 執筆前に扱う情報を「一時的 → 永続的」「手動 → 自動」の軸で 3 レイヤー程度（例: 作業メモリ＝セッション内の一時情報 / プロジェクトの法典＝永続の共有ルール / 成長する知見＝自律蓄積される学習）に整理する。メモリ系に限らずあらゆる技術トピックに応用する。
- 執筆: §4.1〜§4.4 に従う。
- 技術的正確性の担保: 「200 行以下で遵守率 92%」のように説得力のある数値を効果的に使う。バージョン固有の仕様・API・公式ドキュメント URL・リリース日は WebSearch で最新情報を取得する。
- 出力:
/Shared/anytime-markdown-docs/tech/ へ [YYYYMMDD]-[topic].ja.md（[topic] は英語ケバブケース）で保存し、anytime-markdown-output の整形・検証を適用後、索引を再生成する（npm run tech:index。§1.2）。
- 検証: §4.5 のチェックリストで確認する。
5. 試験設計書（test）の記載ルール
AI はテスト設計者、実行・合否判定は人間。テスト「実施」でなく「設計」を担い、観点網羅とケース構造化を行う。成果物は type: test の試験設計書（テストケース一覧）で、自動 e2e と人手のみの試験を区別して設計する。
核心: ①一次情報（Test Basis）に紐づけ推測しない ②観点で発散（ペルソナ＋ISO/IEC 25010）→技法でケース導出 ③各ケースに自動化判定を付け、人手のみの試験を取りこぼさない。
関連: 「実装後にどのテストを書くか・エビデンス」は anytime-impl-test-design（出口から導出）。本章は正式な試験設計書の author を担う。検証は anytime-markdown-check。
5.1. 設計手順
- 対象と Test Basis を特定: 何をテストするか（機能・画面・移行）と、その一次情報（機能仕様書・E2E シナリオ正本・課題/PBI・ヘルプ記事）を特定する。Test Basis は節レベルまで引く。
- テストレベルを決める: unit / integration / e2e / 手動受入。本章は主に e2e＋手動を扱う（unit/型は
anytime-impl-test-design）。
- 観点で発散（抜けを防ぐ）: 7 ペルソナ（§5.2）と ISO/IEC 25010 品質特性を必須フィールドにし、各機能に当てて観点を出す。
- 技法でケース導出: 入力・条件を持つ機能は古典技法で網羅する（§5.3）。
- 自動化判定を付ける: 各ケースを
自動(e2e) / 手動のみ / 半自動 に分類。手動のみは理由を書く（§5.4）。
- トレーサビリティ: 各ケースに Test Basis を引く。コードや仕様で確認できない箇所は推測で埋めず「※要確認（未実施）」と正直に記す。
- レビュー: 観点の偏り（特定ペルソナ/品質特性に集中）を点検。
anytime-impl-test-design のリトマス（バグが入ったら落ちるか）で各ケースを自己点検。
5.2. テスト観点: 7 ペルソナ（観点網羅の発散軸）
| ペルソナ | 観点 |
|---|
| P1 新人 | UI/操作性・分かりやすさ・初見の迷い |
| P2 ベテラン | キーボード高速操作・IME 変換中・ショートカット |
| P3 悪意 | 境界値・不正値・権限外・二重送信・XSS |
| P4 データ整合 | 保存/読込の往復一致・出力 Markdown の整合 |
| P5 移行/互換 | 欠損・異形式・文字コード・件数一致・後方互換 |
| P6 回帰 | 周辺機能・既存挙動への波及 |
| P7 仕様懐疑 | 一次情報との乖離・仕様の曖昧さ検出 |
ISO/IEC 25010 品質特性（機能適切性・性能効率性・互換性・使用性・信頼性・セキュリティ・保守性・移植性）を各ケースの 品質特性 列に入れ、偏りを可視化する。
5.3. テスト技法（入力・条件を持つ機能で適用）
| 技法 | 使う場面 |
|---|
| 同値分割 | 入力を同結果グループに分け代表値を取る |
| 境界値分析 | 最小/最大/境界±1（バグが出やすい） |
| デシジョンテーブル | 条件の組み合わせと結果を表で網羅 |
| 状態遷移 | モード/状態の遷移（例: WYSIWYG⇔Source・比較モード） |
5.4. 自動 e2e と人手のみの試験の区別
各ケースに自動化判定を付ける。人手のみになりやすい代表類型（自動 e2e の射程外）:
- 実機・別ランタイム: VS Code 拡張 webview（Extension Host）など Playwright で駆動しにくいもの → compile→Reload→観測。
- OS/外部連携: OS クリップボード貼付・ファイル D&D・実ネットワークの外部サービス（PlantUML 外部サーバ・OGP 取得）。
- IME・入力デバイス: 日本語変換中の操作（P2）。
- 印刷・出力の見た目: PDF 印刷結果の視覚的正しさ。
- 主観品質・アクセシビリティ: 可読性/字面の良し悪し・スクリーンリーダ等の実 AT・実機クロスブラウザ。
自動化できるのに未自動なケースは 半自動（将来自動化候補）にし、人手のみ（原理的に手動）と区別する。
5.5. テストケース表の列（推奨セット）
anytime-markdown-output のテーブル規約で、機能/観点ごとに横型表を置く:
| ID | テストタイトル | 観点(ペルソナ) | 品質特性 | 技法 | 前提条件 | 操作 | 期待結果 | Test Basis | 自動化判定 | 優先度 |
期待結果 は外部から決定論的に観測できるものに限定（内部状態を書かない）。自動化判定 = 自動(e2e) / 半自動 / 手動のみ。優先度 = P0(回帰実績)/P1/P2。- 巨大化を避け、given/when/then の詳細は E2E シナリオ正本へリンクし、設計書側は観点・技法・判定・トレーサビリティに集中する。
5.6. frontmatter / 索引
type: "test" / category: "test-design"（または e2e）/ related で Test Basis（機能仕様書・E2E シナリオ）へ references。出力後に同フォルダ索引を再生成（npm run spec:index。§1.2）。
5.7. Red Flags
| 兆候 | 正す |
|---|
| 一次情報を引かず期待結果を推測で埋めた | Test Basis を節まで引く。未確認は「※要確認（未実施）」 |
| 自動 e2e のことだけ書き手動試験を落とした | 人手のみ類型（実機/IME/印刷/外部/主観）を必ず1セクション設ける |
| 観点が UI だけに偏った | 7 ペルソナ＋ISO25010 を当てて偏りを点検 |
| AI が合否判定まで書いた | AI は設計者。実施・判定列は人間が埋める空欄にする |
5.8. References
