maintaining-core-documentation

コアドキュメントの維持

このスキルは、あらゆるソフトウェアプロジェクトやリポジトリ向けの、高品質でプロフェッショナルな技術ドキュメントの作成と維持のための包括的なフレームワークを提供します。

目次

• トリガー
• 必須の初期化
• 基本原則
• 技術ライタースキルとの相乗効果
• ドキュメント維持ガイド
• フォーマット規則
• ドキュメントレビュープロセス

トリガー

このスキルは、次のいずれかに該当する場合にトリガーされるべきです。

• ユーザーがドキュメントの作成またはレビューを依頼した場合。
• ユーザーが機能を追加・変更・削除した場合、またはコードベースに重要な変更を加えた場合。
• ユーザーがテストに何らかの変更を加えた場合。
• ユーザーがデプロイに何らかの変更を加えた場合。

必須の初期化

ドキュメントに関するあらゆるタスクを実行する前に、以下の 技術ライタースキルとの相乗効果 セクションのガイダンスに従って、technical-writer スキルの有無を必ず確認しなければなりません。

基本原則

1. ペルソナとスタイル: プロフェッショナル（「エキスパートアーキテクト」）でありながら、技術的かつ親しみやすいトーンを維持します。設計判断の「なぜ」を説明する際には、高レベルなアーキテクチャの視点を用います。
2. ドキュメント間の同期: コアプロパティ（プロジェクト ID、URL、ファイルパスなど）への変更は、該当するすべてのドキュメントファイルに直ちに反映しなければなりません。
3. 既存ドキュメントの読み取り: プロジェクトの現在の状態と意図を理解するために、常に既存のドキュメントファイルを読み取ります。
4. 技術スタック: conductor/tech-stack.md ファイルが存在する場合は、それを読み取って想定される技術スタックを理解します。
5. 技術的な正確性: 既存のドキュメントが正確である、あるいは最新であると仮定してはいけません。ドキュメントを更新する前に、コードベース、構成設定（例: config.py、Makefile、*.tfvars、pyproject.toml）、環境変数名、コマンドフラグを検証します。
6. 不明点について質問する:
   • 設計上の選択や技術選定を確立するのに役立つ質問をします。
   • 根拠が欠けている設計判断について、その根拠を確立するのに役立つ質問をします。
7. 技術ライターとの相乗効果: ドキュメントのメンテナンスを行う際は、technical-writer スキルが存在する場合に限り（そして存在する場合にのみ）、technical-writer スキルを必ず活用しなければなりません。見つからない場合は、以下の 技術ライタースキルとの相乗効果 セクションに従います。

技術ライタースキルとの相乗効果

technical-writer スキルは、ドキュメントのレビューと作成の品質を向上させます。

1. technical-writer スキルの利用可否を判断します。 スキルは存在する? → スキルをロードし、フォーマットについて協力します。 スキルが見つからない? → 以下の「インストールワークフロー」に従います。

2. インストールワークフロー:

   • npx skills ls -g を使用して利用可否を確認します。
   • ユーザーにスキルを推奨します。
   • 承認された場合は、次のコマンドでインストールします: npx skills add https://github.com/shubhamsaboo/awesome-llm-apps --skill technical-writer -g -y

ドキュメント維持ガイド

このスキルによって維持されるべきコアドキュメントを以下に示します。これらのコアドキュメントをそれぞれレビューし、必要に応じて更新しなければなりません。

1. README.md（「ショーウィンドウ」）

• 焦点: 迅速なオンボーディングと高レベルなプロジェクトの目的。
• テンプレート: README.md.template
• サンプル: README.md
• 主要セクション: 概要、主要リンク（ブログ/ライブデモ）、プロジェクト構造（フォルダツリー）、セットアップ（初回のみ vs セッションごと）、便利なコマンド（Markdown テーブルを使用）。
• トリガーには以下が含まれますが、これらに限定されません:
  • 新しいトップレベルディレクトリの追加。
  • コア機能の追加。
  • make ターゲットの追加。
  • ローカル開発セットアップのワークフローの変更。

2. TODO.md (プロジェクト計画)

• フォーカス: プロジェクト全体のロードマップとタスクの追跡。
• テンプレート: TODO.md.template
• メンテナンス条件: このファイルがすでに存在する場合にのみメンテナンスします。たとえば、タスクが達成された場合や、今後のタスクについて議論している場合などに、作成を提案してもかまいません。
• トリガーには以下が含まれますが、これらに限定されません。
  • ステップを完了したとき、またはプロジェクトのタイムラインを更新したとき。
  • 新しい TODO エントリの作成を依頼されたとき。
  • 完了したステップをクローズ済みとしてマークすることを提案するとき。

3. docs/DESIGN.md (ビジュアル & UX)

• フォーカス: ビジュアルアイデンティティ、UX コンポーネント、デザイントークン。UI デザイン連携（例: Google Stitch）で使用できます。
• テンプレート: design.md.template
• サンプル: docs/DESIGN.md
• 主要セクション: ビジュアルアイデンティティ（タイポグラフィ、カラー）、ビジュアルエフェクト（例: グラスモーフィズム）、フロントエンドコンポーネント（レイアウト、カルーセル、ウィジェットなど）、CLI UX（存在する場合）。
• トリガーには以下が含まれますが、これらに限定されません。
  • UI フレームワーク（例: React、Vue、Angular、Svelte など）を実装するとき。
  • 任意の UI コンポーネントを追加または変更するとき。
  • ビジュアルやスタイルを変更するとき（例: index.css のグローバルスタイルの変更）。

4. docs/architecture-and-walkthrough.md (「ブループリント」)

• フォーカス: システム全体のアーキテクチャロジックと設計上の決定。変更によって、docs/architecture-and-walkthrough.md に記録すべき新しい「設計上の決定」(ADR) が生じるかどうかを評価します。
• テンプレート: architecture-and-walkthrough.md.template
• サンプル: docs/architecture-and-walkthrough.md
• 主要セクション: 設計上の決定（根拠を添えた表形式の ADR）、ソリューションアーキテクチャ、サービス/モデルの関係、主要なユーザージャーニー / ウォークスルー
• トリガーには以下が含まれますが、これらに限定されません。
  • 設計上の決定を追加または変更するとき。
  • データベーススキーマを変更するとき。
  • エージェントのオーケストレーションロジックを変更するとき。
  • コーディングフレームワークを追加または変更するとき。
  • インフラストラクチャのホスティングサービスを変更または新たに導入するとき（例: GCP 上）。
  • セキュリティコンポーネントまたは機能を追加するとき。
  • レイヤー（例: フロントエンド、API、バックエンド、永続化など）を追加するとき。

5. docs/testing.md (品質保証)

• フォーカス: アプリケーションの正確性をどのように検証するか。
• テンプレート: testing.md.template
• サンプル: docs/testing.md
• 主要セクション: スコープ（例: Python、フロントエンド、エージェント）、ツール（pytest、ruff など）、CI/CD 環境の詳細（ローカル vs CI=true）、ユニット/統合/E2E テストの説明、手動検証手順（例: レート制限用の curl スクリプト）。
• トリガーには以下が含まれますが、これらに限定されません。
  • テストを追加 / 変更 / 削除するとき。
  • モック戦略を変更するとき。
  • 新しい品質ゲートツールを導入するとき。

6. deployment/README.md（インフラストラクチャ）

• 焦点：インフラストラクチャ環境のプロビジョニングと管理。
• テンプレート：deployment-README.md.template
• サンプル：deployment/README.md
• 主なセクション：デプロイ方法（例：スクリプト、Terraform、またはその両方）、Terraform の構成、前提条件、変数の引き渡し（env.tfvars → 置換 → 実行時）、シークレット管理、CI/CD パイプライン。
• メンテナンス条件：すべてのプロジェクトに、何らかのデプロイに関するドキュメントが必要です。存在しない場合は、作成を提案してください。デプロイプロセスに変更を加えるたびに、このドキュメントを更新してください。
• トリガーには、次の内容が含まれますが、これらに限定されません。
  • 新しい Terraform リソースの追加。
  • API の有効化。
  • デプロイスクリプトの変更。
  • 新しいサービスの追加。
  • IAM ロールの変更またはバインド。
  • インストールの前提条件の更新。
  • CI/CD パイプラインのロジックの更新、GitHub Actions の更新、Cloud Build の更新など。

7. conductor/ ドキュメント（実装の詳細）

• 焦点：製品のロジック、製品のブランディング、ガイドライン、技術スタックの詳細。これらのドキュメントは Gemini Conductor Extension によって自動的に管理されますが、Conductor 以外で変更を行った場合は、その変更を反映するようドキュメントを更新してください。
• 対象ファイル：product.md、product-guidelines.md、tech-stack.md。
• 厳格な除外事項：conductor/ ディレクトリ内のその他のファイルは、workflow.md、tracks.md、setup_state.json、code_styleguides/ または archive/ ディレクトリ内のファイルなどを含め、絶対に変更しないでください。
• メンテナンス条件：コードベースにこれらのドキュメントがすでに存在する場合に限り、メンテナンスしてください。
• トリガーには、次の内容が含まれますが、これらに限定されません。
  • 技術スタックの大幅な変更。
  • 製品のブランディングの変更。
  • 製品ロジックの再定義。
  • 製品の整合性または技術スタックへの準拠状況の監査依頼。

書式ルール

• 見出し：Markdown の各見出しの後には、必ず空行を入れてください（例：# Header\n\nContent）。これにより、すべての Markdown ビューアーで一貫して表示されます。
• 表：読みやすさを向上させるため、設定、モデルのフィールド、設計上の決定には常に表を使用してください。
• コードブロック：すべてのコードは、適切な言語識別子を指定したフェンス付きコードブロックで囲んでください。
• 図（Mermaid または ASCII は絶対に使用しないでください）：
  • いかなるドキュメントファイル（README.md、ARCHITECTURE.md、docs/*.md）でも、テキストベースの mermaid コードブロック（```mermaid）や、ASCII／Unicode の罫線文字を使った図を作成、挿入、出力しないでください。
  • 視覚的な図（アーキテクチャ、コンポーネントの関係、シーケンス、デプロイフロー）が必要な場合は、必ず画像生成ツールを使って PNG 画像を作成し、リポジトリ（例：media/ または docs/images/）に保存して、相対 Markdown リンク（![Diagram Caption](media/diagram.png)）で埋め込んでください。

ドキュメントのレビュープロセス

ドキュメントを更新する際は、このチェックリストをコピーして進捗を記録してください。

Documentation Update Progress:

- [ ] Step 1: Identify which of the core documents are impacted by code changes.
- [ ] Step 2: Verify that NO out-of-scope files (e.g. `workflow.md`, `code_styleguides/`) are included in the review.
- [ ] Step 3: Assess if the change introduces a new "Design Decision" that should be recorded in `docs/architecture-and-walkthrough.md`.
- [ ] Step 4: For all identified core documents, draft updates as per Document Maintenance Guide, and using the appropriate templates in the `./references` directory and using the samples in `./references/samples/`.
- [ ] Step 5: **Structural & Diagram Validation**: Perform a manual or automated check (e.g. using `grep`) to ensure every markdown header is followed by a blank line and that NO `mermaid` blocks or ASCII diagrams were introduced.
- [ ] Step 6: Review against the formatting rules in the [Formatting Rules](#formatting-rules) section.
- [ ] Step 7: Check that the identified core documents have been updated. If any changes have been missed or performed incorrectly, go back to Step 2 and repeat.
- [ ] Step 8: Check that the change aligns to the formatting rules. If not, fix them and go back to Step 6.
- [ ] Step 9: Only finalize and save when all requirements are met.
- [ ] Step 10: Summarise with a table of which documents were updated and what changes were made. Also include which documents (if any) were not updated and why.

まとめ表の形式

ドキュメントのレビュープロセスの最終要約を行う際は、作業を要約するために次の表の構成を使用してください。

ドキュメント	状態	変更概要／理由
README.md	[更新済み／変更なし]	[変更内容の簡単な説明、または更新が不要だった理由]
TODO.md	[更新済み／変更なし]	[例：ステップ 4 を完了としてマーク]
docs/DESIGN.md	[更新済み／変更なし]	[例：frontmatter に新しいカラートークンを追加]
...	...	...