mcpField
C
codebase-documenter

codebase-documenter

github.com/travisjneuman開発107140 回インストール1 日前に更新
リポジトリ

codebase-documenter について

既存のコードベースについて、開発者が初心者にも分かりやすい文書を作成・更新するためのスキルです。README、アーキテクチャ、API、コードコメント、導入ガイドを扱い、背景説明、例、検証を重視します。

主な機能

  1. 01README と導入ガイド
  2. 02アーキテクチャと API の文書
  3. 03背景を説明するコードコメント
  4. 04ファイルツリーとフロー図
  5. 05文書の検証手順

活用シーン

  1. 01新しい開発者向けのプロジェクト文書作成
  2. 02アーキテクチャやデータフローの説明
  3. 03コードコメントへの背景情報の追加
  4. 04コードに照らした文書例の確認

インストール

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

$npx skills add https://github.com/travisjneuman/.claude --skill codebase-documenter

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

同梱ファイル

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

index.js
package.json
assets/templates/
API.template.md
ARCHITECTURE.template.md
CODE_COMMENTS.template.md
README.template.md
references/
documentation_guidelines.md
visual_aids_guide.md

詳細

Codebase Documenter

あらゆるコードベース向けに、包括的で初心者にもわかりやすいドキュメントを作成します。

使用する場面

次の用途に使用します：

  • README ファイルの作成や更新
  • アーキテクチャドキュメントの作成
  • 意味のあるコードコメントの追加
  • API やエンドポイントのドキュメント化
  • 入門ガイドの作成
  • プロジェクト構成の説明

次の用途には使用しないでください：

  • コードレビュー → generic-code-reviewer を使用
  • UX デザインの判断 → generic-ux-designer を使用
  • コード機能の追加 → generic-feature-developer を使用

基本原則

  1. 「なぜ」から始める - 実装の前に目的を説明する
  2. 段階的に説明する - 簡単な内容から複雑な内容へ
  3. 背景を説明する - コードの動作だけでなく、コードが存在する理由も説明する
  4. 例を含める - すべての概念に具体的な使い方を示す
  5. 予備知識がない前提で説明する - 用語を定義し、専門用語を避ける
  6. 視覚的な補助を使う - 図、ファイルツリー、フローチャート
  7. すぐに成果を得られるようにする - 5 分で何かを動かせるようにする

ドキュメント作成ワークフロー

  1. 分析する - エントリーポイント、依存関係、主要概念、設定
  2. 種類を選ぶ - README → アーキテクチャ → API → コメント
  3. 作成する - テンプレートを使い、プロジェクトに合わせて調整する
  4. 検証する - 初心者の視点で読み、コードを読んで例を確認する

ドキュメントの種類

README（プロジェクトのエントリーポイント）
# Project Name

## What This Does

[1-2 sentence explanation]

## Quick Start

[< 5 minute setup]

## Project Structure

[Visual file tree]

## Key Concepts

[Core abstractions]

## Common Tasks

[Step-by-step guides]
アーキテクチャドキュメント
# Architecture Overview

## System Design

[High-level diagram]

## Data Flow

[How data moves through system]

## Key Design Decisions

[Why certain choices were made]

## Extension Points

[Where to add new features]
コードコメント
// ✅ GOOD - Explains WHY and context
// IndexedDB quota check: Prevents silent failures when storage is full.
// Without this, writes fail with cryptic QuotaExceededError.
if (quota.percentUsed > 80) showStorageWarning();

// ❌ BAD - Just repeats what code does
// Check if quota is over 80
API ドキュメント
## Endpoint: POST /api/resource

### What It Does

[Plain-English purpose]

### Request/Response

[JSON examples]

### Common Errors

[Error codes and meanings]

視覚的な表現パターン

ファイルツリー
project/
├── src/                    # Source code
│   ├── components/        # Reusable UI
│   ├── services/          # Business logic
│   └── types/             # TypeScript types
├── tests/                 # Test files
└── package.json           # Dependencies
データフロー
User Request Flow:
1. User submits → 2. Validation → 3. API → 4. Database → 5. Response

[1] components/Form.tsx
    ↓ validates
[2] services/validation.ts
    ↓ calls API
[3] services/api.ts
    ↓ queries
[4] Database
    ↓ returns
[5] Form.tsx (updates UI)
設計判断（ADR）
## Why We Use [Technology]

**Decision:** [What we chose]
**Context:** [Why we needed to choose]
**Reasoning:** [Why this option]
**Trade-offs:** [What we gave up]

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

公開前
  • クイックスタートが 5 分未満で動作する
  • コード例をコピーして貼り付けられる
  • ファイルパスが正確である
  • リンクが機能する
  • 専門用語が定義されている
  • 複雑なフローに図が含まれている
避けるべきよくある間違い
  • 読者がコードベースを知っている前提で説明する
  • コード例が古い
  • 前提条件が不足している
  • 複雑なシステムに視覚的な補助がない
  • 「なぜ」を説明せず、「何を」だけを説明する

検証ワークフロー

ドキュメントを作成した後：

  1. 初見の視点で確認する - コードベースを一度も見たことがないつもりで読む
  2. 例を確認する - 各例を現在のコード、API、および使用するパスと照らし合わせて読む
  3. リンクを確認する - すべての内部リンクと外部リンクが解決できる
  4. 初心者の視点で確認する - 新しい開発者が理解できるか
  5. 更新状況を確認する - 現在のコードが反映されているか

関連項目

コメント

Markdown 対応