file-todos

ファイルベースの Todo 追跡スキル

概要

todos/ ディレクトリには、コードレビューのフィードバック、技術的負債、機能リクエスト、作業項目を管理するためのファイルベースの追跡システムが含まれています。各 Todo は、YAML フロントマターと構造化されたセクションを含む Markdown ファイルです。

次の場合にこのスキルを使用してください。

• 調査結果やフィードバックから新しい Todo を作成する
• Todo のライフサイクルを管理する（pending → ready → complete）
• 承認に向けて pending 項目をトリアージする
• 依存関係を確認または管理する
• PR コメントやコードの調査結果を追跡対象の作業に変換する
• Todo の実行中に作業ログを更新する

ファイル名の規則

Todo ファイル名は次のパターンに従います。

{issue_id}-{status}-{priority}-{description}.md

構成要素：

• issue_id：連番（001、002、003...）。再利用しないでください
• status：pending（トリアージが必要）、ready（承認済み）、complete（完了）
• priority：p1（重大）、p2（重要）、p3（あると望ましい）
• description：kebab-case の簡潔な説明

例：

001-pending-p1-mailer-test.md
002-ready-p1-fix-n-plus-1.md
005-complete-p2-refactor-csv.md

ファイル構造

各 Todo は、YAML フロントマターと構造化されたセクションを含む Markdown ファイルです。新しい Todo を作成する際は、出発点として todo-template.md のテンプレートを使用してください。

必須セクション：

• Problem Statement - 何が壊れているか、不足しているか、改善が必要か
• Findings - 調査結果、根本原因、重要な発見
• Proposed Solutions - 長所・短所、作業量、リスクを含む複数の選択肢
• Recommended Action - 明確な計画（トリアージ時に記入）
• Acceptance Criteria - テスト可能なチェックリスト項目
• Work Log - 日付、作業内容、学びを時系列で記録

任意のセクション：

• Technical Details - 影響を受けるファイル、関連コンポーネント、DB の変更
• Resources - エラー、テスト、PR、ドキュメントへのリンク
• Notes - 追加の背景情報や決定事項

YAML フロントマターのフィールド：

---
status: ready              # pending | ready | complete
priority: p1              # p1 | p2 | p3
issue_id: "002"
tags: [rails, performance, database]
dependencies: ["001"]     # Issue IDs this is blocked by
---

よくあるワークフロー

新しい Todo の作成

調査結果やフィードバックから新しい Todo を作成するには：

1. 次の issue ID を確認します：ls todos/ | grep -o '^[0-9]\+' | sort -n | tail -1
2. テンプレートをコピーします：cp assets/todo-template.md todos/{NEXT_ID}-pending-{priority}-{description}.md
3. 編集して必須セクションを記入します。
   • Problem Statement
   • Findings（調査に基づく場合）
   • Proposed Solutions（複数の選択肢）
   • Acceptance Criteria
   • 最初の Work Log エントリを追加
4. ステータスを決定します：pending（トリアージが必要）または ready（事前承認済み）
5. 絞り込みに関連するタグを追加します

Todo を作成する場合：

• 15～20 分以上の作業が必要な場合
• 調査、計画、または複数のアプローチの検討が必要な場合
• 他の作業との依存関係がある場合
• マネージャーの承認や優先順位付けが必要な場合
• より大きな機能やリファクタリングの一部である場合
• ドキュメント化が必要な技術的負債の場合

代わりにすぐ対応する場合：

• 問題が些細な場合（15 分未満）
• 必要な情報がすべてそろっている場合
• 計画が不要な場合
• ユーザーがすぐに対応するよう明示的に依頼した場合
• 解決策が明白な単純なバグ修正の場合

Pending 項目のトリアージ

pending の Todo をトリアージするには：

1. pending 項目を一覧表示します：ls todos/*-pending-*.md
2. 各 Todo について、次の操作を行います。
   • Problem Statement と Findings を読む
   • Proposed Solutions を確認する
   • 承認、保留、または優先度の変更を判断する
3. 承認された Todo を更新します。
   • ファイル名を変更します：mv {file}-pending-{pri}-{desc}.md {file}-ready-{pri}-{desc}.md
   • フロントマターを更新します：status: pending → status: ready
   • 「Recommended Action」セクションに明確な計画を記入する
   • 初期評価と異なる場合は優先度を調整する
4. 保留された Todo は pending ステータスのままにします

スラッシュコマンドを使用： 対話形式の承認ワークフローには /triage を使用します

依存関係の管理

依存関係を追跡するには：

dependencies: ["002", "005"]  # This todo blocked by issues 002 and 005
dependencies: []               # No blockers - can work immediately

Todo をブロックしている項目を確認するには：

grep "^dependencies:" todos/003-*.md

Todo がブロックしている項目を確認するには：

grep -l 'dependencies:.*"002"' todos/*.md

開始前にブロッカーが完了していることを確認するには：

for dep in 001 002 003; do
  [ -f "todos/${dep}-complete-*.md" ] || echo "Issue $dep not complete"
done

作業ログの更新

TODO に取り組む際は、必ず作業ログのエントリーを追加してください。

### YYYY-MM-DD - Session Title

**By:** Claude Code / Developer Name

**Actions:**
- Specific changes made (include file:line references)
- Commands executed
- Tests run
- Results of investigation

**Learnings:**
- What worked / what didn't
- Patterns discovered
- Key insights for future work

作業ログは、次の目的で使用します。

• 調査の履歴を記録する
• 試したアプローチを文書化する
• チーム内で知識を共有する
• 将来、同様の作業を行う際のコンテキストを提供する

TODO の完了

TODO を完了としてマークするには、次の手順を実行します。

1. すべての受け入れ基準にチェックが付いていることを確認する
2. 最終セッションと結果を作業ログに更新する
3. ファイル名を変更する：mv {file}-ready-{pri}-{desc}.md {file}-complete-{pri}-{desc}.md
4. フロントマターを更新する：status: ready → status: complete
5. ブロック解除された作業がないか確認する：grep -l 'dependencies:.*"002"' todos/*-ready-*.md
6. issue への参照を含めてコミットする：feat: resolve issue 002

開発ワークフローとの連携

トリガー	フロー	ツール
コードレビュー	/ce:review → 指摘事項 → /triage → TODO	レビューエージェント + スキル
PR コメント	/resolve_pr_parallel → 個別の修正 → TODO	gh CLI + スキル
コード内の TODO	/resolve-todo-parallel → 修正 + 複雑な TODO	エージェント + スキル
計画	ブレインストーミング → TODO を作成 → 作業 → 完了	スキル
フィードバック	ディスカッション → TODO を作成 → トリアージ → 作業	スキル + スラッシュコマンド

クイックリファレンスコマンド

作業を探す：

# List highest priority unblocked work
grep -l 'dependencies: \[\]' todos/*-ready-p1-*.md

# List all pending items needing triage
ls todos/*-pending-*.md

# Find next issue ID
ls todos/ | grep -o '^[0-9]\+' | sort -n | tail -1 | awk '{printf "%03d", $1+1}'

# Count by status
for status in pending ready complete; do
  echo "$status: $(ls -1 todos/*-$status-*.md 2>/dev/null | wc -l)"
done

依存関係の管理：

# What blocks this todo?
grep "^dependencies:" todos/003-*.md

# What does this todo block?
grep -l 'dependencies:.*"002"' todos/*.md

検索：

# Search by tag
grep -l "tags:.*rails" todos/*.md

# Search by priority
ls todos/*-p1-*.md

# Full-text search
grep -r "payment" todos/

主な違い

ファイルベースの TODO システム（このスキル）：

• todos/ ディレクトリ内の Markdown ファイル
• 開発／プロジェクトの追跡
• YAML フロントマターを含む独立した Markdown ファイル
• 人間とエージェントが使用

Rails の Todo モデル：

• app/models/todo.rb 内のデータベースモデル
• アプリケーション内のユーザー向け機能
• Active Record の CRUD 操作
• このファイルベースのシステムとは別のもの

TodoWrite ツール：

• エージェントのセッション中に行うメモリ内のタスク追跡
• 1 回の会話に限った一時的な追跡
• ディスクには保存されない
• 上記のどちらのシステムとも異なる