Command Documentation Patterns

概要

このスキルは、Claude Codeコマンドのドキュメンテーションパターンを提供します。 セルフドキュメンティング構造、豊富な使用例、トラブルシューティングにより、 ユーザーフレンドリーで保守しやすいコマンドを作成できます。

主要な価値:

• 自己説明的なコマンド構造
• 豊富な使用例
• 実践的なトラブルシューティング
• 一貫したドキュメンテーション

対象ユーザー:

• コマンドを作成するエージェント（.claude/agents/command-arch.md）
• ドキュメントを充実させたい開発者
• ユーザーフレンドリーなコマンドを作成したいチーム

リソース構造

command-documentation-patterns/
├── SKILL.md                                    # 本ファイル
├── resources/
│   ├── self-documenting-structure.md          # セルフドキュメンティング構造
│   ├── example-patterns.md                    # 使用例パターン
│   ├── troubleshooting-guide.md               # トラブルシューティングガイド
│   └── writing-style-guide.md                 # ライティングスタイルガイド
└── templates/
    ├── full-documentation-template.md         # 完全ドキュメントテンプレート
    └── minimal-documentation-template.md      # 最小ドキュメントテンプレート

リソース種別

• 構造詳細 (resources/*.md): 各ドキュメンテーションパターンの詳細
• スタイルガイド (resources/writing-style-guide.md): ライティング規則
• テンプレート (templates/): ドキュメントテンプレート

いつ使うか

シナリオ1: 新規コマンドのドキュメント作成

状況: 新しいコマンドに適切なドキュメントを追加したい

適用条件:

• ドキュメント構造が不明
• 何を書くべきかわからない
• 一貫性のあるスタイルが欲しい

期待される成果: 完全なドキュメント

シナリオ2: 使用例の追加

状況: コマンドの使い方を示す例を追加したい

適用条件:

• 基本的な使用例のみ
• 高度な使用例が欠けている
• エッジケースの例が必要

期待される成果: 豊富な使用例

シナリオ3: トラブルシューティングの追加

状況: よくある問題と解決方法を文書化したい

適用条件:

• ユーザーが同じ問題で困っている
• エラーメッセージが不明確
• デバッグ方法が不明

期待される成果: 実用的なトラブルシューティング

セルフドキュメンティング構造

完全版テンプレート

---
description: |
  [4-8行の詳細な説明]
  [キーワードを含める]
  [使用タイミングを明記]
argument-hint: [arg1] [arg2]
---

# [Command Name]

## 📋 Purpose

[このコマンドの目的]

## 📥 Input

- `$ARGUMENTS`: [引数の説明]
- `$1`: [第一引数]（必要な場合）
- `$2`: [第二引数]（必要な場合）

## 📤 Output

- [生成されるファイル]
- [コンソール出力]
- [副作用]

## ⚙️ Prerequisites

- [必要な環境]
- [依存関係]
- [権限]

## 🔧 Configuration

このコマンドが参照する設定:

- `.env` ファイル
- `package.json`
- プロジェクト設定ファイル

## 🚀 Execution Steps

1. [ステップ1]
2. [ステップ2]
3. [ステップ3]

## 📝 Examples

### Example 1: Basic usage

```bash
/command basic-input
```

Expected output:

✅ Operation completed successfully
📁 Created: output.txt

Example 2: Advanced usage

/command advanced-input --flag

Expected output:

🔄 Processing with advanced options...
✅ Done

🐛 Troubleshooting

Problem 1: [Common issue]

Symptoms: [What user sees]

Solution:

1. [Step to fix]
2. [Step to verify]

Problem 2: [Another issue]

Symptoms: [What user sees]

Solution: [How to fix]

⚠️ Warnings

• [Important warning 1]
• [Important warning 2]

🔗 Related

• [Related command 1]
• [Related command 2]
• [Documentation link]

### 最小版テンプレート

```markdown
---
description: [Brief description]
---

# [Command Name]

## Purpose
[What this does]

## Usage
```bash
/command [arguments]

Example

/command example-input

Expected: [What happens]

## セクション別ガイド

### Purpose セクション

**良い例**:
```markdown
## 📋 Purpose
This command creates a new React component with:
- TypeScript interface
- Unit tests
- Storybook story
- Export in index file

Use this when you need a fully-configured component ready for development.

悪い例:

## Purpose

Creates component

Input セクション

詳細な説明:

## 📥 Input

### Required

- `$ARGUMENTS`: Component name in PascalCase
  - Must be unique
  - Must not conflict with HTML elements
  - Example: `UserProfile`, `NavigationBar`

### Optional Environment Variables

- `COMPONENT_TEMPLATE`: Custom template path
  - Default: `.claude/templates/component.tsx`
  - Override for project-specific templates

Output セクション

明確な期待値:

## 📤 Output

### Files Created

- `src/components/[Name]/[Name].tsx` - Component implementation
- `src/components/[Name]/[Name].test.tsx` - Unit tests
- `src/components/[Name]/[Name].stories.tsx` - Storybook stories
- `src/components/[Name]/index.ts` - Export file

### Console Output

✅ Component created: UserProfile 📁 Files created: 4 🧪 Tests generated: 3 📚 Story created: 1

Next steps:

1. cd src/components/UserProfile
2. Review generated files
3. pnpm test -- UserProfile

Prerequisites セクション

包括的なリスト:

## ⚙️ Prerequisites

### Environment

- Node.js >= 18.0.0
- pnpm >= 9.0.0

### Dependencies

- React >= 18.0.0
- TypeScript >= 5.0.0
- Testing Library installed

### Permissions

- Write access to `src/components/` directory
- Read access to template files

### Project Structure

Required directories:

src/ └── components/ └── index.ts (must exist)

使用例パターン

レベル1: 基本的な使用

### Example 1: Basic Usage

最もシンプルな形式:

```bash
/create-component Button
```

What happens:

1. Creates Button component in src/components/Button/
2. Generates tests
3. Updates exports

Result:

✅ Button component created
📁 4 files created
🧪 3 tests passing

### レベル2: 一般的な使用

```markdown
### Example 2: With Props
Props付きコンポーネント:

```bash
/create-component UserCard

Then define props when prompted:

interface UserCardProps {
  name: string;
  email: string;
  avatar?: string;
}

Result: Component with typed props interface

### レベル3: 高度な使用

```markdown
### Example 3: Custom Template
カスタムテンプレート使用:

```bash
COMPONENT_TEMPLATE=.claude/templates/advanced-component.tsx \
/create-component Dashboard

This uses your custom template with:

• Advanced state management
• Custom hooks
• Error boundaries

Result: Fully-featured component

### レベル4: エッジケース

```markdown
### Example 4: Nested Component
ネストされたコンポーネント:

```bash
/create-component forms/LoginForm

Creates:

src/
└── components/
    └── forms/
        └── LoginForm/
            ├── LoginForm.tsx
            ├── LoginForm.test.tsx
            └── index.ts

Note: Parent directory forms/ must exist

## トラブルシューティングパターン

### パターン1: 症状 → 原因 → 解決

```markdown
## 🐛 Troubleshooting

### Component already exists
**Symptoms**:

❌ Error: Component 'Button' already exists 📁 Found at: src/components/Button/

**Cause**:
A component with this name already exists in the project.

**Solution**:
1. Choose a different name:
   ```bash
   /create-component PrimaryButton

2. Or delete existing component first:

   rm -rf src/components/Button/
   /create-component Button
   

### パターン2: チェックリスト形式

```markdown
### Build fails after component creation

Run through this checklist:

- [ ] Is TypeScript installed? `pnpm list typescript`
- [ ] Is tsconfig.json valid? `npx tsc --noEmit`
- [ ] Are all imports correct? Check file paths
- [ ] Is the component exported? Check `index.ts`
- [ ] Are tests passing? `pnpm test -- [ComponentName]`

If all checked and still failing:
```bash
# Clear cache and rebuild
rm -rf node_modules/.cache
pnpm run build

### パターン3: FAQ形式

```markdown
### FAQ

**Q: Can I create components in subdirectories?**
A: Yes, use forward slashes:
```bash
/create-component forms/LoginForm
/create-component modals/ConfirmDialog

Q: How do I use a custom template? A: Set COMPONENT_TEMPLATE environment variable:

export COMPONENT_TEMPLATE=./my-template.tsx
/create-component MyComponent

Q: Can I skip tests generation? A: Not with this command. To create component only:

/create-component-no-tests MyComponent

## ライティングスタイル

### 原則

1. **明確さ > 簡潔さ**
   - 曖昧さを避ける
   - 具体的な例を提供
   - 専門用語を説明

2. **能動態を使用**
   - ✓ "Creates a component"
   - ✗ "A component is created"

3. **現在形を使用**
   - ✓ "This command creates..."
   - ✗ "This command will create..."

4. **箇条書きを活用**
   - 長い文章より箇条書き
   - ステップは番号付き
   - オプションは記号

5. **コードブロックを使用**
   - コマンド例
   - 期待される出力
   - 設定ファイル例

### 絵文字の使用

```markdown
推奨される絵文字:

📋 Purpose / Overview
📥 Input
📤 Output
⚙️ Prerequisites / Configuration
🚀 Execution / Steps
📝 Examples
🐛 Troubleshooting
⚠️ Warnings
✅ Success
❌ Error
💡 Tips
🔗 Related / Links
📁 Files
🧪 Tests

トーンとボイス

✓ フレンドリー:
  "Let's create a component together!"

✓ プロフェッショナル:
  "This command generates production-ready components."

✓ 助けになる:
  "If you encounter issues, check the troubleshooting section below."

✗ 技術的すぎ:
  "Instantiates a React functional component utilizing TypeScript generics..."

✗ カジュアルすぎ:
  "Yo, this thing makes components, ya know?"

詳細リソースの参照

セルフドキュメンティング構造

詳細は resources/self-documenting-structure.md を参照

使用例パターン

詳細は resources/example-patterns.md を参照

トラブルシューティングガイド

詳細は resources/troubleshooting-guide.md を参照

ライティングスタイルガイド

詳細は resources/writing-style-guide.md を参照

テンプレート

• 完全版: templates/full-documentation-template.md
• 最小版: templates/minimal-documentation-template.md

コマンドリファレンス

このスキルで使用可能なリソース、テンプレートへのアクセスコマンド:

リソース読み取り

# ドキュメンテーションガイド
cat .claude/skills/command-documentation-patterns/resources/documentation-guide.md

他のスキルのスクリプトを活用

# 知識ドキュメントの品質検証
node .claude/skills/knowledge-management/scripts/validate-knowledge.mjs .claude/skills/command-documentation-patterns/resources/documentation-guide.md

# トークン見積もり
node .claude/skills/context-optimization/scripts/estimate-tokens.mjs .claude/skills/command-documentation-patterns/SKILL.md

# ドキュメント構造分析
node .claude/skills/documentation-architecture/scripts/analyze-structure.mjs .claude/skills/command-documentation-patterns

関連スキル

• .claude/skills/command-structure-fundamentals/SKILL.md - description書き方
• .claude/skills/command-arguments-system/SKILL.md - argument-hint説明
• .claude/skills/command-error-handling/SKILL.md - エラーメッセージ設計

更新履歴

• v1.0.0 (2025-11-24): 初版作成