AgentSkillsCN

documentation-operations

manabe的doc/编辑流程中的运营规范、撰写标准与质量要求。以README.md为唯一入口，从内容质量（元数据、结构、链接）入手，全面统一文档的各项要素。

SKILL.md
--- frontmatter
name: documentation-operations
description: manabe の doc/ を編集する際の運用・記述・品質基準。README.md を唯一の入口として、内容品質（メタデータ・構成・リンク）まで統一する。

ドキュメント運用スキル

このスキルは doc/ 配下のドキュメントを追加・更新・移動するときに使う。

1. まず読むべきもの

  • •doc/README.md（唯一の入口）
  • •doc/decisions/standards/doc-operation-rules.md（運用ルール）

2. 配置・構造ルール（マクロ）

  • •決定済み・参照用 → doc/decisions/<topic>/
  • •未整理・途中 → doc/notes/
  • •古い・使っていない → doc/archive/（整理しない）
  • •迷ったら → doc/notes/
  • •最上位は固定: decisions/, notes/, archive/, templates/, secret/
  • •ディレクトリ階層は 最大3階層（例: doc/decisions/architecture/xxx.md）
  • •各ディレクトリ直下に README.md を置く
  • •1ファイル = 1目的（複数の概念を混ぜない）
  • •内容別に細かく分類しすぎない（関心単位で分ける）

3. ミクロ品質ルール（内容）

以下は Google / Microsoft / Write the Docs / Diátaxis の一般的なベストプラクティスを踏まえた最低基準。

3.1 必須メタデータ

各ドキュメントの冒頭に 必ず 置く。

code
# タイトル

## メタデータ

- Owner: xxxx
- Status: Draft / Active / Archived
- Last Updated: YYYY-MM-DD
- Source of Truth: URL
- Doc Type: Tutorial / How-to / Reference / Explanation
- Audience: 誰向けか
- Scope: 何を扱うか
- Out of Scope: 扱わない範囲
- Related: URL一覧

3.2 リンクは必ず URL

  • •パスは禁止（./foo.md のような相対パスは使わない）
  • •必ず URL を書く
  • •リポジトリ内リンクは以下の形式を推奨
    • •ファイル: https://github.com/<owner>/<repo>/blob/main/doc/...
    • •ディレクトリ: https://github.com/<owner>/<repo>/tree/main/doc/...
  • •コード参照は原則コミット固定のパーマリンクを使う

3.3 内容構成（推奨テンプレート）

最小構成（必須）:

  1. •目的 / 何を解決するか（1〜3文）
  2. •前提・依存（必要なら）
  3. •本文（手順・仕様・判断・根拠）
  4. •関連リンク（URL）

より丁寧に書く場合:

  • •背景 / 問題 / ゴール
  • •決定事項と理由
  • •代替案（なぜ却下したか）
  • •具体例 / サンプル
  • •例外・注意点
  • •変更履歴（重要変更のみ）

3.4 Doc Type の使い分け（Diátaxis）

  • •Tutorial: 初学者向けの流れ重視
  • •How-to: ゴール達成の手順
  • •Reference: 仕様・定義の正確性
  • •Explanation: 背景・理由・設計思想

書く前に「どの型か」を必ず決める。

3.5 スタイル・表現

  • •短い文・短い段落
  • •主語と動詞を明確に（能動態）
  • •見出しは「名詞 + 目的」形式で統一
  • •用語は用語集に合わせる（新語は定義する）
  • •箇条書きと表で可読性を上げる
  • •FAQで本質を逃げない（FAQは補助のみ）

3.6 更新ルール（ミクロ）

  • •内容を変えたら Last Updated を更新
  • •古い情報は削除せず doc/archive/ へ移動
  • •README と doc/README のリンクを同期する

4. 追加・更新の手順（実務）

  1. •変更対象のトピックを決める
  2. •doc/decisions/<topic>/README.md にリンクを追加・更新
  3. •「今、誰かが探すか？」→ Yes なら doc/README.md にも載せる
  4. •古い情報は削除せず doc/archive/ に移動

5. トピック一覧（decisions/）

  • •project/ — プロダクト概要・要件・セットアップ
  • •architecture/ — アーキテクチャ・レイヤー設計
  • •design/ — 画面・データモデル・AI・DI・エラー処理
  • •engineering/ — コーディング・テスト・品質
  • •operations/ — リリース運用
  • •adr/ — 意思決定記録
  • •standards/ — 運用ルール・用語集・記法

6. 禁止事項

  • •分類ルールの追加
  • •archive/ 内の整理
  • •README.md 以外の入口作成