---
description: TODOコメント自動検出・Issue化
---

# Miyabi TODOコメント自動検出

コード内のTODOコメントを自動的に検出して、GitHub Issueを作成します。

## MCPツール

### `miyabi__todos`
TODOコメントをスキャンしてIssue作成

**パラメータ**:
- `path`: スキャン対象パス（デフォルト: `./src`）
- `autoCreate`: 自動的にIssue作成するか（デフォルト: false）

**使用例**:
```
TODOをスキャンして表示:
miyabi__todos({ path: "./src" })

TODOを検出して自動的にIssue作成:
miyabi__todos({ path: "./src", autoCreate: true })

プロジェクト全体をスキャン:
miyabi__todos({ path: "." })
```

## 動作フロー

```
コードベーススキャン
    ↓
TODOコメント検出
    ↓
重複チェック（既存Issueとの照合）
    ↓
[autoCreate=true の場合]
    ↓
GitHub Issue自動作成
    ↓
適切なLabel付与
    ↓
結果レポート表示
```

## 検出パターン

Miyabiは以下のパターンのTODOコメントを検出します:

### 基本パターン
```typescript
// TODO: ユーザー認証機能を追加
// FIXME: エラーハンドリングを改善
// HACK: 一時的な回避策（後で修正）
// XXX: 要確認・注意が必要
// NOTE: 重要な実装メモ
```

### 優先度付き
```typescript
// TODO(P0): 緊急対応が必要
// TODO(P1): 高優先度
// TODO(P2): 通常優先度
// TODO(P3): 低優先度
```

### 担当者指定
```typescript
// TODO(@username): ユーザー認証実装
// FIXME(@team-frontend): UIバグ修正
```

### 期限付き
```typescript
// TODO(2025-12-31): 年内に実装
// FIXME(before-v1.0): リリース前に修正
```

### 複合
```typescript
// TODO(P1)(@backend-team)(2025-11-01): API実装
```

## Issue作成時のLabel付与

自動的に以下のLabelが付与されます:

| TODOタイプ | Label | 優先度 |
|-----------|-------|--------|
| TODO | `type:feature`, `source:code-todo` | 規模により自動判定 |
| FIXME | `type:bug`, `source:code-fixme` | 緊急度-中 |
| HACK | `type:refactor`, `source:code-hack` | 技術的負債 |
| XXX | `type:investigation`, `source:code-xxx` | 要確認 |
| NOTE | `type:docs`, `source:code-note` | ドキュメント |

### 優先度マッピング
- `P0` → `緊急度-即時`
- `P1` → `緊急度-高`
- `P2` → `緊急度-中`
- `P3` → `緊急度-低`

## コマンドライン実行

MCPツールの代わりにコマンドラインでも実行可能:

```bash
# TODOをスキャンして表示
npx miyabi todos --path ./src

# 自動的にIssue作成
npx miyabi todos --path ./src --auto-create

# 特定のパターンのみ検出
npx miyabi todos --path . --pattern "TODO|FIXME"

# ドライラン（Issue作成しない）
npx miyabi todos --path ./src --auto-create --dry-run
```

## 環境変数

`.env` ファイルに以下を設定:

```bash
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
REPOSITORY=owner/repo
```

## 出力形式

### スキャン結果（autoCreate=false）

```
📝 TODOスキャン結果

検出: 15件

src/auth/login.ts:42
  // TODO(P1): MFA対応を追加
  タイプ: TODO
  優先度: P1
  ファイル: src/auth/login.ts:42

src/api/users.ts:123
  // FIXME: レート制限エラー処理を改善
  タイプ: FIXME
  ファイル: src/api/users.ts:123

...

サマリー:
  TODO: 8件
  FIXME: 4件
  HACK: 2件
  XXX: 1件

推奨アクション:
  1. npx miyabi todos --auto-create でIssue化
  2. 高優先度(P0/P1)から対応
```

### Issue作成結果（autoCreate=true）

```
📝 TODOスキャン & Issue作成

検出: 15件
作成: 12件（既存3件スキップ）

✅ Issue #145作成: [TODO] MFA対応を追加
   ファイル: src/auth/login.ts:42
   Label: type:feature, source:code-todo, 緊急度-高
   URL: https://github.com/owner/repo/issues/145

✅ Issue #146作成: [FIXME] レート制限エラー処理を改善
   ファイル: src/api/users.ts:123
   Label: type:bug, source:code-fixme, 緊急度-中
   URL: https://github.com/owner/repo/issues/146

...

スキップ: 3件（既存Issueあり）
  - "ユーザー認証機能を追加" → Issue #120
  - "エラーハンドリングを改善" → Issue #98
  - "一時的な回避策" → Issue #77

サマリー:
  作成: 12件
  スキップ: 3件
  失敗: 0件
```

## 重複チェック

既存Issueとの重複を防ぐため、以下をチェックします:

1. **タイトル類似度**: 既存IssueタイトルとのLevenshtein距離
2. **ファイルパス**: 同じファイル・行数のTODOは重複とみなす
3. **Labelパターン**: `source:code-todo` Labelで既存TODO由来Issueを検出

重複判定されたTODOはスキップされ、既存Issue URLが表示されます。

## Issueテンプレート

自動作成されるIssueは以下の形式:

```markdown
## 📝 コード内TODO

**タイプ**: TODO
**優先度**: P1
**ファイル**: src/auth/login.ts:42

### 内容

MFA対応を追加

### コンテキスト

\`\`\`typescript
// TODO(P1): MFA対応を追加
async function login(email: string, password: string) {
  // 現在の実装
  return authenticateUser(email, password);
}
\`\`\`

### 推奨アクション

- [ ] MFA実装の設計
- [ ] TOTP/SMS認証の選択
- [ ] バックアップコード生成
- [ ] テスト追加

---

🤖 Generated by Miyabi Todos Auto Mode
Source: src/auth/login.ts:42
```

## 除外パターン

以下のファイル・ディレクトリは自動的にスキップされます:

```
node_modules/
.git/
dist/
build/
coverage/
*.min.js
*.bundle.js
*.test.ts
*.spec.ts
```

カスタム除外パターンを `.miyabi.yml` で設定可能:

```yaml
todos:
  exclude:
    - "legacy/**"
    - "deprecated/**"
    - "*.generated.ts"
```

## 使用例

### 例1: スキャンのみ

```
あなた: "src/配下のTODOコメントをスキャンして"

Claude: [miyabi__todos({ path: "./src" }) を実行]

📝 TODOスキャン結果

検出: 8件

src/auth/login.ts:42 - TODO(P1): MFA対応を追加
src/api/users.ts:123 - FIXME: レート制限エラー処理を改善
src/db/connection.ts:56 - HACK: 一時的な接続プール回避策
...

サマリー: TODO 4件, FIXME 2件, HACK 2件
```

### 例2: 自動Issue化

```
あなた: "TODOコメントを全部Issue化して"

Claude: [miyabi__todos({ path: ".", autoCreate: true }) を実行]

📝 TODOスキャン & Issue作成

✅ Issue #145作成: [TODO] MFA対応を追加
✅ Issue #146作成: [FIXME] レート制限エラー処理を改善
✅ Issue #147作成: [HACK] 接続プール回避策を修正
...

完了: 8件のIssueを作成しました
```

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

### TODOが検出されない
```
⚠️  No TODO comments found

確認:
1. パスが正しいか確認（相対パスまたは絶対パス）
2. TODOコメント形式が正しいか確認
3. 除外パターンに該当していないか確認
```

### Issue作成に失敗
```
❌ Failed to create issue: Unauthorized

解決策:
1. GITHUB_TOKEN が設定されているか確認
2. repo権限があるか確認
3. リポジトリへの書き込み権限があるか確認
```

### 重複Issue作成
```
ℹ️  Skipped (duplicate): Issue #120 already exists

これは正常動作です。既存Issueがある場合は自動的にスキップされます。
```

## ベストプラクティス

### 🎯 推奨ワークフロー

1. **定期スキャン**: 週次でTODOをスキャン
2. **優先度付け**: P0/P1から順に対応
3. **クリーンアップ**: 完了したTODOはコードから削除
4. **ドキュメント化**: 重要なTODOはIssueに移行

### ⚠️ 注意事項

- **コメント削除**: Issue化後もTODOコメントは自動削除されません（手動削除推奨）
- **重複チェック**: 既存Issueがある場合は新規作成されません
- **Label付与**: 自動付与されるLabelは `.miyabi.yml` でカスタマイズ可能

### 📝 TODOコメントの書き方

**Good**:
```typescript
// TODO(P1)(@backend-team): ユーザー認証APIを実装
// FIXME(before-v1.0): メモリリーク修正
// HACK: 一時的な回避策 - Issue #123で根本対応予定
```

**Bad**:
```typescript
// todo: あとでなんとかする（曖昧）
// FIXME（全角カッコは検出されない）
// TODO 直す（内容が不明確）
```

---

💡 **ヒント**: TODOコメントは「未来の自分への伝言」です。具体的に書きましょう。