コードを書かないSE日誌

SE歴26年。コードを書かずにClaude Codeで8体のAIエージェントチームを動かしています。AIエージェント・自動化・GTDの実験日誌。

Claude Code の /todo スキルをOSS化するまで——V1モノリスからV2三層設計へ

claudecode gtd nodejs octokit javascript

V1を振り返る

Claude Code の /todo スキルを最初に作ったとき、すべてを1つのMarkdownファイルに書いた。

Claudeへの指示、バリデーション用のbash case文、日付変換ロジック、エラーハンドリング——これらが混在した巨大な todo.md だ。開発日記によると、V2の開発途中でこのファイルが2,011行に達した記録が残っている（V1当初の正確な行数はgit履歴で確認できなかった）。

何が問題だったか。Claudeへの「指示」と、毎回同じ結果を返す「定型コード」が区別されていなかったことだ。

Claudeはファイル全体を読んでから実行する。バリデーションのbash case文も、API呼び出しのコードブロックも、毎回コンテキストを消費する。修正したいときはMarkdownの中からロジックを探す必要があり、セキュリティバリデーションのコードレビューすらMarkdownを読まないとできない状態だった。

V2: 三層への分離

V2で採った設計はシンプルだ。

V2の構成:
  todo.md            ← Claudeへの指示のみ
  todo-engine.js     ← Node.jsエンジン（コードのみ）
  todo.sh            ← シェルラッパー（接続のみ）

todo.md の行数は176行（ローカルデプロイ版・実測）。todo.sh は33行（実測・空行含む全行）。todo-engine.js のサイズは114,026バイト（実測）。

分離の設計思想はこうだ。Claudeへの指示書には、Claudeが判断に使う情報だけを書く。定型コードは書かない。

todo.md にはコマンドの仕様と振る舞いのルールだけを記述する。todo-engine.js は普通のNode.jsスクリプトで、Claude非依存だ。Claudeはこのエンジンを呼び出す指示を出すだけでよい。

「コードをJSに移しただけで、総量は変わっていないじゃないか」という指摘はそのとおりだ。コードの量は減っていない。何が変わったかというと、テストが書けるようになったことと、コードレビューの対象が明確になったことだ。Markdownに埋め込まれたbash case文はユニットテストを書けない。分離されたJS関数なら書ける。

Claude Codeを使った開発の全体像を学びたい場合は、以下の書籍も参考になる。

Claude CodeによるAI駆動開発入門

Octokitマイグレーションと、Windowsで踏んだ2つの罠

V1では GitHub 操作をすべて gh CLI で実行していた。各コマンドがプロセスを生成するため、複数のAPI操作が必要な場合は逐次プロセス起動が走る。

V2では @octokit/rest を使ってNode.jsから直接HTTP通信する構成に変えた。これで apiMain という1つの非同期関数にすべてのGitHub API操作を集約できた（list-issues, view-issue, create-issue, edit-issue, close-issue など）。1関数に集約したことでエントリポイントは単純になる一方、関数内の分岐は増えるため、コマンド種別が増えるほど保守コストが上がるトレードオフがある。

Windowsで実装したため、2つの罠を踏んだ。

罠1: @octokit/rest はESM only

require() が使えない。import() を使う必要があるが、Windowsのパスをそのまま渡すと動かない。pathToFileURL() で変換してから動的インポートする形で解決した。

const { Octokit } = await import(pathToFileURL(octokitPath).href);

罠2: Node.js 24 + Octokit で exit code 3221226505

process.exit(1) を呼ぶとHTTP接続プールが開いたまま libuv の assertion error が発生し、exit code 3221226505（16進で 0xC0000409、Windows のスタックオーバーランエラー（STATUS_STACK_BUFFER_OVERRUN））でクラッシュする。

対処は process.exit を throw に変えること。例外を上位に伝播させてNode.jsが自然終了するようにした。現状のコードを確認したところ、process.exit は62箇所残っている（デプロイ済みファイルで実測）。入力バリデーション（コマンド引数チェック）など、Octokit起動前のパスに集中している。Octokit使用後のパスでは throw を使っている。完全な置き換えではなく、クラッシュが発生する経路を限定的に対処した形だ。

この exit code 3221226505 の件が公式 Issue に報告されているかは未確認。

Windows 固有の Node.js 罠はこれだけではない。開発中に踏んだもう一つの地雷（os.homedir() が HOME を無視する問題）は「テストが ~/.claude/ を消し飛ばした話」に詳しく書いた。

新機能: GTDの「回し方」が変わった

アーキテクチャ刷新に伴って、いくつかの機能を追加した。V1 時代にこれらの機能を使ってエージェントを動かした1日の記録は「Claude Code のエージェントに /todo を持たせたら、1日で記事3本+実装3件が回った話」にある。

routine カテゴリ（GTD 6→7カテゴリ）

V1のGTDカテゴリは6つだった。

V1: inbox / next / waiting / someday / project / reference
V2: inbox / next / routine / waiting / someday / project / reference

routine は繰り返しタスク専用のカテゴリだ。GTDの原典にはないが、習慣タスクと緊急タスクが next に混在する問題を解決するために追加した。

today コマンドと dashboard

V1では朝に /todo list を実行すると全タスクが一覧表示され、「今日何をすべきか」を自分で読み解く必要があった。これを解決するために追加した。

/todo today で今日のスコープだけを表示する。4セクション構成だ。

  • 期限超過タスク
  • 今日が期限のタスク
  • 今日のルーティン
  • 未実施のルーティン

dashboard は1週間スコープ。朝は today、週次レビュー前は dashboard と使い分けられる。

ラベルの絵文字化

GitHub Mobileでの視認性向上のため、GTDラベルに絵文字プレフィックスを追加した。PCブラウザではテキストラベルでも区別できるが、スマホでは一覧の視認性が低かった。

📥 inbox  🎯 next  🔁 routine  ⏳ waiting  🌈 someday  📁 project  📎 reference

その他の追加機能

  • help コマンド: コマンド数が増えてコマンド名を覚えられなくなったため追加。カテゴリ別（タスク管理 / コンテキスト / 一括操作 / レビュー・分析）で一覧表示する
  • i18n（英語対応）: LANG_ENV=en で主要な出力メッセージが英語になる（カバレッジ未測定）。翻訳辞書（MESSAGES オブジェクト）のキー数は未確認。日付入力は言語設定に関係なく日英両対応しており、「明日」も「tomorrow」も常に受け付ける。英語対応の実装詳細は「Claude Code の /todo コマンドを英語対応した（LANG_ENV=en）」で解説している

日本語日付パーサーと --group オプション

「AIが毎回やっている定型処理をスキルやシェルに切り出せる箇所はないか」と分析したところ、2つが浮かび上がった。

1つ目は日付入力だ。/todo add タスク名 --due 金曜 と書いても、AIが「金曜 = 2026-04-17」と手動変換してGitHub APIに渡していた。この変換は毎回同じ結果を返す純粋な計算なのに、毎回コンテキストを消費していた。

V2では --due と due コマンドで日本語の相対表現をそのまま受け付ける。変換はNode.js側で処理する（JSTベース）。

対応している表現:

今日 / きょう
明日 / あした / あす
明後日 / あさって
昨日 / きのう
月曜〜日曜（次の該当曜日）
今週金曜 / 来週月曜 など
来週（来週月曜）
来月（来月1日）

2つ目は一覧の並び替えだ。/todo list の出力をAIが毎回期限別にテーブル整形していた。これも定型処理だ。

list に --group オプションを追加し、エンジン側でグルーピングして出力する。表示順は固定で、期限超過 → 今日 → 明日 → 今週 → 来週以降 → 期限なしの順だ。

どちらも前述の「指示書には判断に使う情報だけ、定型処理はスクリプト化」という方針の延長だ。この2機能の追加でテストも35件増えた（398件 → 433件）。

OSS化のためにやったこと

V1は自分のリポジトリ名をコードに直書きしていた。

# V1（例）
REPO="saitoko/000-partner"

これを環境変数に変えた。

# V2
export TODO_REPO_OWNER="your-org"
export TODO_REPO_NAME="your-repo"

.env.example を用意してあるので、クローンして変数を設定するだけで動く。GH_TOKEN は .env に書くか、gh auth token で自動取得する。

セットアップ手順は README に書いてある。ただし前提は「Node.js が入っていること」と「GitHub CLI (gh) がインストールされていること」だ。CoWork（Claude の Web環境）でも動くよう、todo.sh が .env ファイルを複数階層で探索する仕組みも入れている。

テストについて正直に書く

「テスト600件超」とネタ帳に書いてあったが、実際に run-tests.sh のアサーション数を数えたところ378件だった（実測）。その後、日本語日付パーサーと --group オプションの追加で55件増え、現在は433件だ。

開発日記に記録されているテスト数の変遷はこうだ。

時点 件数
Day 1 終了 174件
Day 2 夜 300件
Day 2 深夜 330件
Day 3（i18n対応後） 437件 ※1

※1 表の値はV2開発日記の記録値。本文の433件は直近の実測値（378件 + 55件）。開発日記記録後に統合・削除等によるアサーション数の変動があった可能性がある。

378件は機能追加前の実測値であり、その後55件の増加で現在の433件に至っている。

テストの構成は §1〜§28 のローカルテスト1本だ。run-tests.sh の冒頭には「GitHub には接続しない」と明記されており、日付正規化・バリデーション・文字列組み立てなど todo-engine.js の純粋な関数テストのみで構成されている。GitHub APIを使う統合テストは含まれていない。

現在地と残課題

公開リポジトリは https://github.com/saitoko/claude-todo-gtd だ。

まだできていないこと、うまくいっていないことも書いておく。

  • process.exit が62箇所残っており、Windows環境での挙動は「問題が出るパスを避けた」状態。完全な解決ではない
  • テスト件数の「600件超」という数字は実態と合っていなかった。正確な計測ができていなかった
  • i18n の翻訳カバレッジは未測定。「全出力メッセージが英語化」と書いているが、漏れがないかの確認は取れていない
  • CoWork以外の環境での動作確認は限定的。Windows + Node.js 24 の組み合わせでしか実測していない

Pro版機能（ダッシュボード、デイリーレビュー、カスタムビュー、レポート）の実装詳細は別記事に書く予定だ。

V1ユーザーは todo-engine.js と todo.sh を追加し、.env に環境変数を設定すれば移行できる。todo.md の内容も更新が必要なため、リポジトリの最新版を参照してほしい。

Claude Codeのスキル開発をより体系的に進めたいなら、こちらも手元に置いておくと役立つ。

実践Claude Code入門

まず動かしてみる（新規ユーザー向け3ステップ）

リポジトリ: https://github.com/saitoko/claude-todo-gtd

  1. リポジトリをクローンし、npm install を実行する
  2. .env.example をコピーして .env を作成し、TODO_REPO_OWNER と TODO_REPO_NAME を自分のGitHubリポジトリに設定する（GH_TOKEN は gh auth token で自動取得するため通常は不要）
  3. todo.sh と todo.md をClaude Codeのカスタムスキルとして配置し、/todo help を実行する

前提は Node.js（v18以上）と GitHub CLI（gh）がインストール済みであること。

V2 の全機能（チクラーファイル・プロジェクト棚卸し自動化・someday の⚠️バッジ・見積もり機能）をまとめたガイドは「今度こそ！ Claude Code で GTD を回す /todo 完全ガイド」で読めます。

/todo スキルをV2に育てると、次の問いが出てくる——このスキルをエージェントに持たせて、実際にタスクを自律処理させるにはどう設計すればいいのか？

私はスキルの三層化と並行して、Claude Code のマルチエージェント設計を試行していた。スキルの設計原則（指示書と実行コードの分離）は、エージェント組織の設計原則と同じ構造を持っていた。その全体像を書いたのが以下の本だ。序章と第1部は無料で読める。

AIチームを作るまで——Claude Code でマルチエージェントを設計する