mcpField
D
documentation-engineer

documentation-engineer

github.com/zhaono1開発85713 回インストール9 週間前に更新
リポジトリ

documentation-engineer について

明確で保守しやすい技術文書の作成を支援するスキルです。README、API、コードコメント、アーキテクチャの記述を扱い、チェックリストと検証の指針も提供します。

主な機能

  1. 01READMEの構成と執筆指針
  2. 02APIとコード文書の指針
  3. 03アーキテクチャ文書の概要
  4. 04執筆原則とチェックリスト
  5. 05文書の生成・検証の指針

活用シーン

  1. 01プロジェクトREADMEの草案作成
  2. 02公開関数やAPIの文書化
  3. 03システム構成とデータフローの説明
  4. 04文書の網羅性の確認

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/zhaono1/agent-playbook --skill documentation-engineer

インストール後、Claude Code で/documentation-engineerを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

README.md
references/
api-template.md
readme-template.md
style-guide.md
scripts/
generate_docs.py
validate_docs.py

詳細

ドキュメントエンジニア

明確で包括的、かつ保守しやすい技術ドキュメントの作成に精通しています。

このスキルが有効になる場面

次のような場合に有効になります。

  • ドキュメントの作成を依頼する
  • README の作成を依頼する
  • 「docs」または「これをドキュメント化して」と伝える
  • API ドキュメントが必要な場合

ドキュメントの種類

1. README

すべてのプロジェクトに、次の内容を含む README が必要です。

# Project Name

Brief description (what it does, why it exists)

## Quick Start

Installation and usage in 3 steps or less.

## Installation

Detailed installation instructions.

## Usage

Examples of common usage patterns.

## Configuration

Environment variables and configuration options.

## Development

How to run tests, build, and develop locally.

## Contributing

Guidelines for contributors.

## License

License information.
2. API ドキュメント

各エンドポイント／関数について、次の内容を記載します。

  • 説明：何をするか
  • パラメーター：名前、型、必須／任意、説明
  • 戻り値：型と構造
  • エラー：発生しうるエラーと条件
  • 例：使用例
3. コードコメント

何をするかではなく、なぜそうするのかをコメントします。

// Bad: Sets the count to zero
count = 0;

// Good: Reset count for new measurement cycle
count = 0;

// Bad: Check if user is admin
if (user.role === 'admin') {

// Good: Only admins can bypass approval workflow
if (user.role === 'admin') {
4. アーキテクチャドキュメント
  • システムの概要
  • コンポーネント間の関係
  • データフロー
  • 設計上の決定事項
  • 検討したトレードオフ

ドキュメント作成の原則

  1. 明確にする：簡潔で直接的な言葉を使います
  2. 簡潔にする：読者の時間を尊重します
  3. 正確にする：コードとドキュメントを同期させます
  4. 網羅する：すべての公開インターフェースを扱います
  5. 最新に保つ：コードが変更されたらドキュメントも更新します

執筆ガイドライン

見出し
  • 見出しは文頭のみ大文字にします
  • 動詞または名詞で始めます
  • 内容が分かる見出しにします
コード例
  • 適切な場合は変更前と変更後を示します
  • インポート文を含めます
  • 想定される出力を示します
  • エッジケースに対応します
リンク
  • 内部ドキュメントには相対リンクを使います
  • セクションへのアンカーを含めます
  • リンクが機能することを確認します
図
  • フローチャートやシーケンス図には Mermaid を使います
  • 図はシンプルに保ちます
  • タイトルと凡例を追加します

ドキュメントチェックリスト

README
  • プロジェクトの説明
  • クイックスタートガイド
  • インストール手順
  • 使用例
  • 設定ガイド
  • コントリビューションガイドライン
コードドキュメント
  • すべての公開関数を文書化する
  • パラメーターと戻り値を文書化する
  • 複雑な関数には例を示す
  • エッジケースを文書化する
API ドキュメント
  • すべてのエンドポイントを文書化する
  • リクエスト／レスポンスのスキーマ
  • 認証要件
  • エラーレスポンスを文書化する
  • レート制限を文書化する

スクリプト

ドキュメントの構成を生成します。

python3 scripts/generate_docs.py --name <service-name> --output docs/README.md

ドキュメントを検証します。

python3 scripts/validate_docs.py --input docs/README.md

参考資料

  • references/readme-template.md - README テンプレート
  • references/api-template.md - API ドキュメントテンプレート
  • references/style-guide.md - ドキュメントスタイルガイド

コメント

Markdown 対応