clickupfy-dev

開発向け ClickUpfy

Promovaweb の ClickUpfy またはその MCP ツールを使用して、エンジニアリング業務を参照・更新します。回答は簡潔にし、変更の追跡可能性を維持します。

継続的なドキュメント整備

ClickUpfy に変更を加えるときは、docs/user/、ebook/README.md、docs/user/reading-order.txt、README.md、ドキュメントテストを確認します。新しいコマンド、フラグ、引数、MCP ツール、出力形式、API の制限、動作変更には、適切なリファレンスの章で説明、パラメーター、効果、制限、異なる使用例を5つ記載する必要があります。

また、詳細なリファレンスをリンクで置き換えず、ユースケースに沿った手順にもコマンドまたはツールを含めます。ドキュメントを変更した場合は、電子書籍のバージョンを更新し、PDF と EPUB を再生成して、電子書籍の検証を実行します。ヘルプテキストや名前の一覧に表示されているという理由だけで、インターフェースがドキュメント化されていると主張してはいけません。

インターフェースを選択する

1. MCP サーバーが利用できる場合は、clickupfy_* ツールを使用します。
2. MCP ツールが利用できない場合は、ターミナルから clickupfy を使用します。
3. まず clickupfy_mcp_context を実行して、プロジェクトの MCP で固定されている接続先を確認します。
4. MCP が利用できない場合は、clickupfy account list を使用します。
5. 単発の参照のためだけにアクティブなプロファイルを切り替えるのではなく、--account <perfil> または account 引数を指定します。

~/clickupfy/config.json の apiKey フィールドを、読み取り、表示、コメント、コピーしてはいけません。コマンド、ログ、コミット、回答に認証情報を含めてはいけません。

プロジェクトの分離を維持する

作業フォルダーの .mcp.json をエージェントの接続先として扱います。API キーを保存せず、clickupfy mcp serve の引数でプロファイル、workspace、Space、Folder、必須の List を固定します。Sprint Folder が表示されるのは、プロジェクトで Sprints を使用する場合のみです。

並行しているプロジェクト間の切り替えに account use を実行してはいけません。プロジェクトごとに独自のサーバーを維持します。最初の書き込み前に clickupfy_mcp_context を確認し、すでに固定されている ID は省略します。サーバーは、起動時に受け取った引数と異なるプロファイルや階層を拒否します。

CLI は .mcp.json を読み取りません。MCP が利用できない場合は、プロファイルと ID を明示的に指定します。

clickupfy --account <perfil> task list --list <list-id>

作業を探す

名前または説明の一部が分かっている場合は、workspace 内を検索します。

clickupfy task search --query "<texto>"

MCP では clickupfy_tasks_search を使用します。検索結果に候補となるタスクが複数ある場合は、ClickUp に書き込む前に選択肢を提示し、どれを選ぶか尋ねます。

検索だけでは不十分な場合は、階層をたどって ID を特定します。

clickupfy workspace list
clickupfy space list
clickupfy folder list --space <space-id>
clickupfy list list --folder <folder-id>
clickupfy list get <list-id>
clickupfy task list --list <list-id>

list が folder に属していない場合は、list list で --space <space-id> を使用します。コンパクトなフィールドだけでは不十分な場合は、--json を追加します。

MCP では、同じ順序で次を使用します。

• clickupfy_workspaces_list；
• clickupfy_spaces_list；
• clickupfy_folders_list；
• clickupfy_lists_list；
• clickupfy_list_get；
• clickupfy_tasks_list。

workspace、space、folder、list、タスク、ユーザーの ID を推測してはいけません。

Sprints で計画する

このセクションは、clickupfy_mcp_context で Sprint Folder が通知された場合、またはユーザーがスコープに Sprint を含めた場合にのみ適用します。

階層から Sprint Folder を特定し、計画を変更する前にアクティブな Sprint を確認します。

clickupfy sprint list --folder <sprint-folder-id>
clickupfy sprint current --folder <sprint-folder-id>
clickupfy sprint get <sprint-id>
clickupfy sprint tasks <sprint-id> --open-only

MCP では clickupfy_sprints_list、clickupfy_sprint_current、clickupfy_sprint_get、clickupfy_sprint_tasks を使用します。Sprint は start_date と due_date を持つ List です。Sprint Folder 内の通常の List を Sprint として扱ってはいけません。ClickUp のパブリック API ではこの操作が提供されていないため、CLI では Sprints を作成できません。

ユーザーが Sprint の計画をスコープに含めた場合にのみ、タスクを関連付けるか削除します。

clickupfy sprint add-task <sprint-id> <task-id>
clickupfy sprint remove-task <sprint-id> <task-id>
clickupfy sprint set-points <task-id> <points>

MCP では、同等の操作として clickupfy_sprint_add_task、clickupfy_sprint_remove_task、clickupfy_sprint_set_points を使用します。変更のたびに Sprint とタスクを再確認します。

変更前に読む

1. clickupfy task get <id> --json または clickupfy_task_get でタスク全体を取得します。
2. execution.summary を読み、execution.items を返された順に確認します。
3. 保留中の各 key を個別の作業単位として扱い、 parentKey と depth を保持します。
4. clickupfy comment list --task <id> --json または clickupfy_comments_list でコメントを読みます。
5. 関連するステータス、説明、担当者、日付、サブタスク、依存関係を 確認します。
6. タスクとプロファイルが依頼された対象範囲に属していることを確認します。

clickupfy_task_get は、親タスク、ネストされたサブタスク、チェックリスト項目を すでにまとめて取得します。名前からこの階層を再構築しないでください。タスクには task:<id>、チェックリスト項目には checklist:<checklist-id>:<item-id> のキーを 使用します。

エージェントがタスク全体を単一のテキストコンテキストとして必要とする場合は、 clickupfy task get <id> --markdown を使用するか、 markdown: true を指定して clickupfy_task_get を呼び出します。項目を 選択して更新するために構造化されたキューが必要な場合は、このオプションを 指定せずに JSON レスポンスを使用します。

チェックリスト項目を完了したら、その項目自体に用意された complete アクションを 実行します。手動で完了または再開するには：

clickupfy checklist set <task-id> <checklist-id> <item-id> --resolved
clickupfy checklist set <task-id> <checklist-id> <item-id> --open

MCP では clickupfy_checklist_item_set を使用します。このツールは書き込み後に タスクを再読み込みし、done が指定された状態と一致する場合にのみ項目を返します。

チェックリストとその項目を作成するには：

clickupfy checklist create <task-id> --name "Testes"
clickupfy checklist item-create <checklist-id> --name "<teste>"

MCP では clickupfy_checklist_create と clickupfy_checklist_item_create を使用します。作成中は各項目を未完了のままにします。

タスクを更新する

依頼で許可されたフィールドのみを使用します：

clickupfy task create \
  --list <list-id> \
  --name "<nome>" \
  --markdown-content "<markdown>" \
  --parent "<task-id>" \
  --start-date <AAAA-MM-DD> \
  --due-date <AAAA-MM-DD>

clickupfy task update <task-id> --status "<status exato>"
clickupfy task update <task-id> --start-date <AAAA-MM-DD>
clickupfy task update <task-id> --priority 2
clickupfy task update <task-id> --points 5
clickupfy comment create --task <task-id> --text "<progresso>"

MCP では clickupfy_task_create、clickupfy_task_update、 clickupfy_comment_create を使用します。対応するフィールドには markdownContent、parent、startDate、dueDate を使用します。ステータスは List ごとに設定された名前です。clickupfy_list_get を読み、実際の表記を使用します。

task delete または clickupfy_task_delete の前に、明示的な承認を取得し、 ID を確認します。MCP ツールでは confirm: true、CLI では --yes が必要です。

時間を記録する

まず、既存の time entry があるか確認します：

clickupfy time current
clickupfy time start --task <task-id> --description "<atividade>"
clickupfy time stop

MCP では clickupfy_time_current、clickupfy_time_start、 clickupfy_time_stop を使用します。実行中の time entry がある場合、現在の記録を どう扱うか確認せずに別の time entry を開始しないでください。同じプロファイルと workspace を使う並行プロセスがある場合、この確認は必須です。

変更を検証する

書き込みのたびに：

1. タスクまたは変更したリソースを再度読み込みます。
2. 保存された値と依頼された値を比較します。
3. ID、確認できた変更、実際に残っている未完了事項を報告します。
4. コマンドでエラーが発生しなかったことだけを根拠に、成功したと報告してはいけません。