Help / Purple Codens

Purple Codens セットアップ

AI 開発オーケストレーション。タスクを切って Claude Code に実装させ、PR を出すまでを自動化します。Fargate / VPS 上で並列実行され、長時間タスクや並走タスクも安定して捌けます。

概要

Purple Codens は workflow run という単位でタスクを管理します。1 つの run は「タスクの仕様 → 実装 → テスト → PR 作成」までを一気通貫で実行します。途中で fix_verify ループや heartbeat job も自動で走ります。

Fargate executor: 1 タスク = 1 ECS Fargate task として隔離実行（デフォルト）
VPS executor: 専用 VPS プールを借りて長時間タスクや GPU 依存タスクを実行（Enterprise オプション）
Workflow 仕様: feature → develop → main の 3 段階フローが既定。base_branch も指定可能

前提条件

Codens アカウントと organization が作成済み（Getting Started 参照）
codens-mcp がインストール済み・ログイン済み（MCP セットアップ参照）
対象 GitHub リポジトリへの admin / write 権限
Codens GitHub App をインストール済み（https://github.com/apps/codens から install。Purple project 作成時にも install フローへ誘導されます）

Step 1. プロジェクト作成 + repo 紐付け

ダッシュボード（app.purple.codens.ai）から「New Project」を選択するか、MCP 経由でまとめてセットアップできます。

MCP 経由（推奨）

// ローカル repo をその場で解析 → project 作成 → repo link → instruction import を一括
await tools.purple_project({
  action: "init_project",
  repo_full_name: "Corevice/your-repo",
  name: "Your Repo",
  base_branch: "develop"
});

// 既存 project の一覧
await tools.purple_project({ action: "list_projects" });

init_project は内部で次を実行します: (1) Purple project 作成 / (2) GitHub repo link / (3) repo の CLAUDE.md と .claude/rules/ を取得して instruction として登録。

Step 2. Instruction (CLAUDE.md / rules) 同期

repo の CLAUDE.md と .claude/rules/*.md を Purple に取り込むと、workflow run 内の Claude Code が同じガイドラインを参照して実装します。

// 取り込み済みファイルの一覧
await tools.purple_instruction({ action: "list", project_id });

// repo 側の最新と diff を取って同期
await tools.purple_instruction({ action: "sync", project_id });

verify_commands を強化するのがコツです。pytest だけで終わらせず test -f / grep -q を併用すると、fix_verify ループが効きやすくなります（.claude/rules/verify-commands.md 相当のガイド推奨）。

Step 3. 最初の workflow run を投げる

// タスクを投入
const run = await tools.purple_workflow({
  action: "create_workflow",
  project_id: "...",
  name: "Add rate limiting to login API",
  spec: {
    repository: "Corevice/your-repo",
    base_branch: "develop",
    description: "Apply 10 req/min per IP using Redis-backed limiter. Add tests."
  }
});

// 進捗を確認（status: pending → running → succeeded / failed）
await tools.purple_workflow({ action: "get_run_status", run_id: run.run_id });

// SSE で stream 購読する場合
await tools.purple_sse({ action: "subscribe_run_events", run_id: run.run_id });

完了すると PR URL が返ります。失敗時は purple_log で詳細ログ（S3 presigned URL、1 時間有効）を取得できます。

運用上のポイント

長時間 heartbeat job: 動作中の run に purple_workflow({ action: "inject_message" }) で割り込みメッセージを送れる
キャンセル: purple_workflow({ action: "cancel_run" })。meta/parent タスクは Ready for Agent にしないこと（cascade される）
verify_commands: uv venv .venv && uv pip install ... を必ず明示。.gitignore された venv/ や node_modules/ は worktree に存在しない
独立 git repo: codens-main 配下では各 Codens プロダクトが独立 repo。commit / push は各ディレクトリ内で実行

より詳しいシナリオはユースケース A — Purple workflow を参照。

次のステップ