Anthropicが提供するClaude Codeを使用して、TypeScript製のCLIツールをつくりました。Claude Codeのような自走力の高いAIエージェントとうまくやっていく方法を考えつつ、Notion MPCとの連携といったセットアップの方法を記事にまとめます。
プロジェクトの説明
今回はお試しでつくったのは「cowtodo」という、Markdownファイル内のTODOリストを解析して、cowsayで表示するCLIツールです。
主な機能
- Markdownファイル内の
- [ ]や- [x]の形式で書かれたタスクを解析 - 完了/未完了のタスクを分類して表示
- cowsayライブラリを使用したアスキーアートによる表示
- ファイル監視による自動更新
技術スタック
開発プロセス
開発は以下のようなプロセスで進めました。
- 要件定義: 機能要件の明確化
- 開発環境の構築: プロジェクト初期設定
- 基本機能の実装: Markdownのタスク解析とUIコンポーネント作成
Claude Codeの設定
プロジェクトのタスク管理にはNotionを使います。
タスク管理のイメージ
Notion MCPのセットアップ
まずはClaude CodeからNotionで作成したテーブルへアクセスできるように、MCP連携をセットアップします。基本的にはリポジトリのセットアップ手順を行うだけです。
- NotionのIntegrationを作成 (APIキーの発行)
- プロジェクトルートに
.mcp.jsonを追加 -
.gitignoreに.mcp.jsonを追加
.mcp.json
{
"mcpServers": {
"notionApi": {
"command": "npx",
"args": ["-y", "@notionhq/notion-mcp-server"],
"env": {
"OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer \", \"Notion-Version\": \"2022-06-28\" }"
}
}
}
}
claude を起動して「タスクの一覧を表示してください。」とプロンプトしてみます。Notionと連携できていると、Claudeが以下のように結果を返してくれます。
> タスクの一覧を表示してください。
⏺ タスクの一覧を確認します。
省略...
⏺ Notionのタスク一覧：
1. 【TAS8】cowtodo
- ステータス：未着手
- 担当者：yuki
- 期限：2025-05-11
- サブタスク：要件定義
2. 【TAS9】要件定義
- ステータス：未着手
- 担当者：yuki
- 期限：2025-05-11
- 親タスク：cowtodo
ユーザー設定
Claude Codeのユーザー設定として、User memoryとClaude Code settingsの2つがあります。どちらもプロジェクトを跨いで有効となるため、共通項を括り出して設定しておくと便利です。
- User memory: 自分好みのコーディングスタイルなどを記載
- Claude Code settings: 許可・拒否するコマンドなどを記載
User memoryのサンプル
私は CLAUDE.md だけでなく、言語やライブラリごとにファイルを分割して管理しています。
~/.claude/CLAUDE.md
# General
- ユーザーとの対話には日本語を使う
- ユーザーの指示なく、以下の作業を行わない
- 次のタスクを開始
- Git コミット
- GitHub にプッシュ
- `~/.ssh`にアクセスしない
## コーディングガイドライン
### コミットメッセージ
- コミットメッセージは英語で書く
- Conventional Commits のルールに従う
### コード内コメント
- コード内コメントは英語で書く
### コーディングスタイル
`~/.claude`ディレクトリにある言語やライブラリごとのルールをを参照する。
## タスク管理
- Notion の`test_tasks`でタスク管理を行う
- Notion の`test_tasks`以外のページは参照しない
- ワークフローが途中で失敗した場合、ユーザーに判断を委ねる
### タスク着手時のワークフロー
親タスクの PR が作成されていない場合、以下の手順に従う。
その後、サブタスク開始時のワークフローを実行する。
#### 親タスク
1. 親タスクの状態を「着手中」に変更
2. Git で main からブランチを作成 (ブランチ名は`story/`とする)
3. 空コミットを作成 (コミットメッセージは`chore: start story/`とする)
4. PR を作成 (`gh pr create --assignee @me --base main --draft`)
5. タイトルはタスクのタイトルを参照する (`【】`)
6. ボディはタスクの内容から生成する (Notion タスクへのリンクを含める)
7. プロンプトをユーザーに返す
#### サブタスク
1. サブタスクの状態を「着手中」に変更
2. タスクの開始日時を設定 (時間まで記載すること)
3. Git で親タスクからブランチを作成 (ブランチ名は`feature/`とする)
4. 空コミットを作成 (コミットメッセージは`chore: start feature/`とする)
5. PR を作成 (`gh pr create --assignee @me --base --draft`)
6. タイトルはタスクのタイトルを参照する (`【】`)
7. ボディはタスクの内容から生成する (Notion タスクへのリンクを含める)
8. 実装計画を考えて、ユーザーに伝える
9. プロンプトをユーザーに返す
### タスク完了時のワークフロー
親タスクの完了はユーザーが行うため、サブタスクに対して以下の処理を行う。
1. PR のステータスを ready にする
2. PR をマージ (`gh pr merge --merge --auto --delete-branch`)
3. タスクの開始日時を設定 (時間まで記載すること)
4. タスクに「サマリー」を追加
5. コマンドライン履歴とコンテキストを参照して、振り返りを効率かするための文章を作成
6. Notion の見出しは「振り返り」とする
7. タスクの状態を「完了」に変更
8. タスクの完了日時を記載 (時間まで記載すること)
## レビュー
ユーザーから PR のレビュー依頼があった場合、以下の観点でコードのレビューを行う。
- 仕様をすべて満たしているか確認
- タスクにチェックリストがある場合、すべてにチェックが入っているか確認
- タイポがないか確認
- コードベースの一貫性を保てているか確認
- より好ましい実装があればユーザーに提案
~/.claude/typescript.md
# TypeScript
## 命名規則
フロントエンド、バックエンドを問わず以下の命名規則に従う。
- ディレクトリ名: ケバブケース
- ファイル名: ケバブケース
- コンポーネント名: パスカルケース
- 型名: パスカルケース
## モジュール
- ライブラリやフレームワークの制限がない限り、Named exports を使用する
- `export`は対象とする関数や定数の先頭に書く
- 相対パスによるインポートは同一モジュール内でのみ許可する
## 関数定義
- すべてのケースで Arrow Function を使用する
Claude Code settingsのサンプル
rm などのコマンドには注意が必要です。
~/.claude/settings.json
{
"permissions": {
"allow": [
"Bash(git *)",
"Bash(gh *)",
"Bash(npm *)",
"Bash(npx *)",
"Bash(mkdir *)",
"Bash(mv *)",
"Bash(cp *)",
"Bash(touch *)",
"Bash(ls *)",
"Bash(cat *)",
"Bash(echo *)",
"Bash(pwd)",
"Bash(open *)"
]
}
}
プロジェクト設定
/init を実行すると、プロジェクトルートに CLAUDE.md が生成されます。その後、ユーザー設定を参考に CLAUDE.md の更新を指示すると、ベースとなるプロジェクトの設定を作成してくれます。以降は必要に応じて更新するとして、プロジェクトの作成時は基になるファイルがあると楽です。
> /init is analyzing your codebase…
⏺ I'll analyze the repository and create a CLAUDE.md file to help future instances of Claude Code work with this
codebase.
省略...
⏺ CLAUDE.mdファイルを作成しました。プロジェクトはまだ初期段階のようですが、現時点でわかる情報に基づいて記載しました
。開発が進むにつれて、開発コマンドやアーキテクチャの詳細を更新することをお勧めします。
> ユーザー設定を参照してCLAUDE.mdを更新してください。
⏺ ユーザー設定を参照してCLAUDE.mdを更新します。
省略...
⏺ ユーザー設定を反映してCLAUDE.mdを更新しました。ユーザーとの対話には日本語を使用すること、コーディングガイドライン
、タスク管理のワークフローなどの情報を追加しました。
開発ワークフロー
CLAUDE.md に開発ワークフローを記載することで、タスクの開始〜終了まで定型的な作業を半自動的に行ってくれます。私の場合は、タスクとGit (GitHub) の操作をお願いしています。
CLAUDE.md
### タスク着手時のワークフロー
1. タスクの状態を「着手中」に変更
2. タスクの開始日時を設定 (時間まで記載すること)
3. Git で main からブランチを作成 (ブランチ名は`feature/`とする)
4. 空コミットを作成 (コミットメッセージは`chore: start feature/`とする)
5. PR を作成 (`gh pr create --assignee @me --base main --draft`)
- タイトルはタスクのタイトルを参照する (`【】`)
- ボディはタスクの内容から生成する (Notion タスクへのリンクを含める)
6. 実装計画を考えて、ユーザーに伝える
7. ユーザーにプロンプトを返す
### タスク完了時のワークフロー
1. PR のステータスを ready にする
2. PR をマージ (`gh pr merge --merge --auto --delete-branch`)
3. タスクの開始日時を設定 (時間まで記載すること)
4. タスクに「サマリー」を追加
- コマンドライン履歴とコンテキストを参照して、振り返りを効率かするための文章を作成
- Notion の見出しは「振り返り」とする
5. タスクの状態を「完了」に変更
6. タスクの完了日時を記載 (時間まで記載すること)
7. ユーザーにプロンプトを返す
タスクの開始
タスク開始時は「タスクのステータス更新 〜 PRの作成」までを自動的にやってくれます。
> タスク「実行環境の構築」を着手します。
⏺ 「実行環境の構築」タスクに着手します。まずはNotionからタスク情報を取得しましょう。
省略...
⏺ Update Todos
⎿ ☒ タスク情報を取得して確認する
☐ タスクの開始手順を実行する
☐ ライブラリのセットアップを行う
☐ src/index.tsにルートファイルを追加する
☐ ルートファイルにcowsayを使った出力コードを実装する
☐ 出力のテストを実施する
⏺ タスクの開始手順を進めていきます。まず、タスク状態を「着手中」に変更します。
⏺ 次に、サブタスク用のブランチを作成します。まず現在のブランチを確認します。
⏺ このブランチから新しいfeatureブランチを作成します。
⏺ 空コミットを作成します。
⏺ ブランチをリモートにプッシュします。
⏺ PRを作成します。
⏺ Update Todos
⎿ ☒ タスク情報を取得して確認する
☒ タスクの開始手順を実行する
☐ ライブラリのセットアップを行う
☐ src/index.tsにルートファイルを追加する
☐ ルートファイルにcowsayを使った出力コードを実装する
☐ 出力のテストを実施する
Update Todos とあるように、Claude CodeにはTODOリストを表示してくれる機能があります。しかし、この時点でClaudeと実行計画を擦り合わせないと、暴走して明後日の方向に向かってしまうのが怖いです。そこで対策として、 タスク開始時に実行計画をユーザーに確認すること、およびユーザーの許可なくタスクを開始しないことを CLAUDE.md に明示しています。
タスクの完了
タスク完了時は「PRのマージ 〜 タスクのステータス更新」までを自動的にやってくれます。
> タスクをクローズします。
⏺ わかりました。タスクを完了の手順を実行します。
まず、PRをレディ状態にします：
⏺ 次に、PRをマージします：
⏺ タスクの状態を「完了」に変更し、完了日時を設定します：
要件定義
ここからは開発プロセスに入っていきます。
まずは、Notionのタスクで簡単に要件をまとめましょう。
要件定義のイメージ
この時点で仕様に関する曖昧な点など、Claudeからのフィードバックを得ます。会話を何往復かすると、仕様がブラッシュアップされるため、その結果を要件定義の成果物である docs/spec.md に出力してもらいます。
> タスク「要件定義」を着手します。
まずはNotionから情報を読み込んでください。
質問があればお願いします。
⏺ 「要件定義」タスクに着手します。Notionから詳細情報を読み込みます。
省略...
⏺ これから「要件定義」の作成を進めていきます。Notion情報を元に、要件定義ドキュメントを作成します。
⏺ Write(file_path: docs/SPEC.md)…
⎿ Wrote 102 lines to docs/SPEC.md
# Cowtodo 要件定義
## 概要
Cowtodoは、引数で受け取ったテキストファイル内のTask list
itemsを解析して、cowsayを経由して標準出力に表示するCLIツールです。
## 実行例
```
$ cowtodo todos.md
… +92 lines (ctrl+r to expand)
> ファイル名は `spec.md` にしてください。
⏺ 承知しました。ファイル名を小文字の spec.md に変更します。
⏺ Write(file_path: docs/spec.md)…
⎿ Error: File has not been read yet. Read it first before writing to it.
⏺ 要件定義ドキュメントを作成しました。Notionの情報に基づいて、cowtodoプロジェクトの要件をdocs/spec.mdにまとめました。
> 要件定義の内容でユーザはタスクを作成する予定です。
何か曖昧な点などはありませんか？
⏺ 要件定義を確認し、曖昧な点や明確にしておくべき点を検討します。
⏺ Read(docs/spec.md)…
⎿ Read 102 lines (ctrl+r to expand)
⏺ 現状の要件定義を確認したところ、いくつか曖昧な点や明確にしておくべき点があります：
1. コマンドライン引数の詳細仕様
- ヘルプオプション（-h, --help）や他のオプション引数の有無
- 多数のファイルを一度に処理する際の制限（上限数があるか）
2. 出力フォーマット
- cowsayのキャラクターを変更するオプションは必要か（デフォルト牛以外）
- 出力の文字数制限（長いタスク名が表示されるとき省略するか）
- 各グループ（BacklogとDone）内でのタスクの表示順序（アルファベット順？出現順？）
3. ネストされたタスクの扱い
- サブタスクの深さに制限はあるか（例：何階層まで対応するか）
- 深いネストの表示方法の詳細
4. インストール方法
- グローバルインストールとローカルインストールの両方をサポートするか
- 必要な Node.js のバージョン要件
5. コンテナ対応
- Docker環境でも実行できる必要があるか
これらの点を明確にしておくと、実装段階でより具体的な方針を持って開発を進められると思います。
開発環境の構築
開発環境の構築では、以下をゴールとしてClaude Codeにすべての作業を任せました。
- tsxでcowsayを使った簡単なプログラムを実行できること
- 必要なライブラリのインストールが完了していること
- Prettier、ESLintのセットアップが完了していること
期待とのギャップ
実際にやってみて、期待通りの結果が得られない部分がありました。
| 項目 | 期待した結果 | 実際の結果 |
|---|---|---|
| 実行方法 |
index.ts を tsx index.ts で実行できる |
index.js が作成され、node index.js で実行できる |
| 開発支援ツール | Prettier, ESLint, Husky をセットアップ | Prettier, ESLint, Husky, lint-staged, commitlint をセットアップ |
開発時の実行方法 npm run dev がうまく伝わっていなかったり、指示していないツールまで
セットアップされています。反省を踏まえて、今後は以下の2点を意識しようと思います。
- 実行計画の粒度を細かくするため、タスクの内容を記述する
- 🙅 Claudeの1タスクが「開発支援ツールのセットアップ」になっている
- 🙆 Claudeの1タスクが「Prettierのセットアップ」になっている
- 予想と違った時点で速やかにタスクを中断させる
- タスクの処理中であっても、Escキーを2度押すと停止できる
- プロセスを終了した場合も、
claude --resumeで再開できる
基本機能の実装
CLIツールの開発は初めてなので勝手がわかりませんでしたが、Claudeが爆速でベース部分をつくってくれました。アウトプットされたコードは普段私が書いているコードに似通っている訳でもなければ、特段きれいでもありませんでしたが、特に0 -> 1のようなケースでは操縦席をあけ渡した方が圧倒的に早いなと思いました。
機能の実装については、複数ファイルが指定された場合の「タスクの並び順」には苦戦していた印象があります。期待する結果はテキストで伝えられるため、実装できるまでClaudeに頑張ってもらい、最終的には要件通りのコードを出してくれました。
その過程で、完成していないPRを何度もマージされてしまったので、ユーザーが指示を出すまでPRをマージしないことを明記することをお勧めします。
最終的に出来上がったもの
おわりに
Claude Codeを使った開発を体験しました。一連の開発フローの中で特に大切だと思ったのは、AIエージェントの歩幅を調整する能力です。
いつコードを書いてもらうかのタイミングもそうですが、開発のフェーズやエンジニアの持つ知識に応じて適切なプロンプトを与えることで、Claudeがうまく自走してくれる実感があります。これからも、こういった感覚を磨きつつ、Claude Codeのある開発に馴染んで行こうと思います。
Views: 2
