Plan Canvas
계획 및 시각적 아티팩트를 위한 검토 루프: 당신이 아티팩트를 작성하면, 사람이 브라우저에서 검토합니다 — 정확히 원하는 요소에 주석을 달고, 채팅하며, 계획 승인 / 변경 요청 결정을 내립니다 — 그리고 당신은 단일 CLI 호출에서 차단 대기하다가 피드백을 JSON으로 반환받습니다.
lavish-axi에서 영감을 받았으며; ECC 네이티브로 /plan 확인 게이트 주변에 의존성 없이 재구축되었습니다.
사용 시점
- 방금 계획 아티팩트(
/plan에서 생성된.claude/plans/*.plan.md)를 작성하고 CONFIRM/승인 결정이 필요할 때 — 캔버스 결정이 입력된 "yes/proceed"를 대체합니다. - 사용자가 무엇을 변경할지 정확히 지정해야 할 때: 디자인, 비교, 보고서 또는 모든 로컬
.md/.html아티팩트 검토. - 사용자가
/plan-canvas, 시각적 검토, 또는 "브라우저에서 열어주세요"를 요청할 때.
다음에는 사용하지 마세요: diff 코드 리뷰(/code-review), 웹 앱 실행, 또는 원격 URL. 캔버스는 로컬 아티팩트 파일만 제공합니다.
작동 방식
CLI를 ecc-plan-canvas로 호출합니다 — ecc-universal 패키지로 제공되는 바이너리입니다 (전역/플러그인 설치 후 PATH에 있음; 플러그인 설치의 경우 node "$CLAUDE_PLUGIN_ROOT/scripts/plan-canvas.js"도 작동). 검토 중인 프로젝트에서 실행하세요; 모든 작업 디렉토리에서 작동합니다. 분리된 루프백 서버(127.0.0.1:4517)를 관리하며, 아티팩트 경로를 키로 사용하여 모든 세션이 공유합니다 — 추적할 세션 ID가 없습니다.
워크플로우는 일반 CLI-더하기-JSON 루프이므로 모델 및 하네스에 구애받지 않습니다: 셸 명령을 실행하고 stdout을 읽을 수 있는 모든 에이전트(Claude Code, Codex, Cursor, Gemini, OpenCode, Copilot)가 동일하게 구동합니다. 하네스가 기술을 표시하는 방식에 따라 트리거하십시오 — 예를 들어 Claude Code에서는 /plan-canvas, Codex에서는 $plan-canvas — 또는 ecc-plan-canvas 명령을 직접 실행하십시오.
# 1. 사용자 브라우저에서 아티팩트 열기 (즉시 반환)
ecc-plan-canvas open .claude/plans/feature.plan.md
# 2. 사람이 응답할 때까지 차단. 계속 실행; 중단되면 다시 실행:
# 대기 중인 피드백은 절대 손실되지 않습니다.
ecc-plan-canvas await .claude/plans/feature.plan.md
계속 듣고 있어야 합니다. 그렇지 않으면 사용자는 빈 의자와 대화합니다
피드백은 await이 실제로 세션에 대기하고 있을 때만 도달합니다. 당신의 턴이 아무것도 듣지 않은 상태로 끝나면 메시지는 대기열에 남아 있고, 사용자 화면에서는 전송이 아무 효과도 없는 것처럼 보입니다.
따라서 await을 백그라운드 작업으로 실행하십시오 (하네스가 지원하는 경우 — Claude Code에서는 run_in_background: true가 있는 Bash 호출). 피드백이 도착하는 즉시 종료되고 하네스가 JSON을 전달하므로, 포그라운드 호출과 함께 죽지 않고 여러 턴에 걸쳐 루프가 유지됩니다. 포그라운드 await도 작동하지만, 하네스가 시간 제한을 걸 때까지만 유효합니다.
두 가지 백스톱이 있으며, 어느 것도 위 사항을 생략하는 핑계가 될 수 없습니다:
ecc-plan-canvas pending은 리스너가 없는 대기 중인 피드백을 나열합니다. 무언가를 놓쳤는지 확실하지 않을 때 확인하십시오.stop:plan-canvas-pending훅은 캔버스 피드백이 전달되지 않은 상태에서 턴이 끝나는 것을 차단하고 메시지를 전달합니다. 해당 훅에서 피드백을 읽고 있다면, 너무 일찍 듣기를 중단한 것입니다.
await은 사용자가 행동할 때 JSON을 출력합니다:
{
"status": "feedback",
"items": [
{ "kind": "annotation", "text": "이것을 두 단계로 나누세요",
"anchor": { "selector": "h2:nth-of-type(3)", "tag": "h2", "snippet": "2단계: 마이그레이션" } },
{ "kind": "verdict", "verdict": "request-changes" }
]
}
kind: "chat"— 자유 형식 메시지; 터미널이 아닌 캔버스에서 답변하세요.kind: "annotation"— 요소에 고정된 피드백 (anchor.selector,anchor.snippet은 사용자가 가리킨 대상을 보여줍니다; 사용자가 구절을 강조 표시한 경우anchor.textRange.text도 포함).kind: "verdict"—approve는 계획이 CONFIRM되었음을 의미합니다: 폴링을 중지하고, 세션을 종료하고, 구현을 시작하세요.request-changes는 아티팩트를 수정하고(캔버스는 라이브 리로드됨) 루프를 계속 유지하라는 의미입니다.
3. 항상 캔버스에서 응답한 다음 계속 듣습니다. 하나의 명령으로 두 가지를 모두 수행할 수 있습니다:
ecc-plan-canvas await <file> --reply "요청하신 대로 2단계를 분할했습니다. 확인해 보세요."
모든 사용자 메시지에는 캔버스에서 답장을 보내야 합니다. "지금 위험 테이블을 다시 작성 중입니다." 같은 한 줄짜리 메시지도 포함됩니다. 채팅 패널의 침묵은 깨진 캔버스와 구별할 수 없으며, 이것이 바로 이 루프가 방지하고자 하는 실패입니다. 터미널에서만 답장하지 말고 거기서 답하세요.
작업하는 동안 활동 표시기로 채팅을 정직하게 유지하세요:
# 애니메이션 "에이전트가 생각 중입니다..." 버블; 긴 작업 중에 새로고침
ecc-plan-canvas typing <file> --state thinking
# 답장이 도착하기 직전에 "에이전트가 입력 중입니다..."로 전환
ecc-plan-canvas typing <file> --state typing
await은 배치를 전달하는 즉시 thinking을 설정하고, --reply는 이를 해제합니다. 두 상태 모두 자체 만료되므로, 충돌한 에이전트는 사용자를 영원히 점(…)만 보게 하는 대신 정직한 "대기 중"으로 표시됩니다. 수정 작업이 1분 이상 걸리면 thinking을 새로고침하세요.
4. 검토가 끝나면 종료합니다: ecc-plan-canvas end <file>.
다이어그램 (Mermaid)
계획의 일부가 흐름, 아키텍처, 시퀀스, 상태 머신, ER 모델 또는 의존성 그래프인 경우, ASCII 아트나 긴 문단 대신 펜스 처리된 ```mermaid 블록으로 작성하세요 — 캔버스는 사용자가 가리킬 수 있는 테마 다이어그램으로 렌더링합니다. 그림이 문단보다 빠르게 읽힐 때 사용하고, 단순한 목록이나 테이블에는 건너뛰세요.
```mermaid
flowchart LR
A[시장 결정] --> B{관찰자?}
B -->|예| C[작업 대기열에 추가] --> D[작업자에게 분배]
```
다이어그램은 ECC 다크 테마와 악센트 팔레트로 렌더링됩니다. Mermaid는 고정된 CDN에서 브라우저로 로드됩니다; CDN을 사용할 수 없는 경우(오프라인), 블록은 소스 코드를 표시하도록 대체되므로 검토가 차단되지 않습니다. 오프라인 환경에서는 ECC_PLAN_CANVAS_MERMAID_URL을 로컬 미러로 지정하세요.
규칙
- 마크다운 아티팩트는 ECC의 계획 템플릿으로 렌더링됩니다 (Mermaid 블록 포함);
.html아티팩트는 주석 레이어가 삽입된 상태로 있는 그대로 렌더링됩니다. HTML 작성 지침은frontend-design-direction및artifact-design기술을 사용하세요. - 수정하려면 아티팩트 파일을 편집하세요 — 캔버스는 저장 시 라이브 리로드됩니다. 새로고침을 위해
open을 다시 실행하지 마세요. {"status": "ended", "endedBy": "user"}(또는 피드백 배치에sessionEnded: true)는 사용자가 검토를 종료했음을 의미합니다: 폴링을 중지하고, 남은 업데이트를 채팅으로 전달하고, 다시 열지 마세요. 해당 세션에 대한 일반open은 거부됩니다; 사용자가 재개를 요청하는 경우에만--reopen을 사용하세요.- 관련 자산(이미지, CSS)은 아티팩트와 같은 위치에 있어야 하며 상대 경로로 참조되어야 합니다.
- 서버는 루프백 전용이며 30분 유휴 시간(
ECC_PLAN_CANVAS_IDLE_MS) 후에 종료됩니다;stop은 명시적으로 종료합니다. 상태는~/.claude/plan-canvas/에 저장됩니다 (ECC_PLAN_CANVAS_STATE_DIR).
예제
계획 승인 흐름 — /plan이 .claude/plans/notifications.plan.md를 작성하고 CONFIRM을 기다려야 함:
ecc-plan-canvas open .claude/plans/notifications.plan.md
ecc-plan-canvas await .claude/plans/notifications.plan.md
# → {"status":"feedback","items":[{"kind":"verdict","verdict":"approve"}]}
ecc-plan-canvas end .claude/plans/notifications.plan.md
# 계획이 확인됨 — 구현 시작
수정 루프 — 피드백이 도착하면, 파일을 편집하고, 답장하고, 계속 듣기:
# await이 주석을 반환 → .plan.md를 편집 (캔버스 라이브 리로드)
ecc-plan-canvas await <file> --reply "위험 테이블을 재작업했습니다."
# → 다음 응답까지 다시 차단
안티-패턴
- 루프에서
--timeout-ms를 사용한 폴링. 테스트용으로 존재합니다. 대신 일반await을 실행 상태로 두세요. - 검토가 아직 열려 있는데
await없이 턴을 종료하는 것. 이것이 사용자가 "메시지를 보냈는데 아무 일도 일어나지 않았습니다"라고 경험하는 유일한 실패입니다. - 피드백을 읽었지만 터미널에서만 답변하는 것. 사용자는 캔버스를 보고 있습니다.
- 사용자가 종료한 후 "그냥 보여주기 위해" 다시 여는 것.
- 전체 계획을 채팅에 붙여넣기 하고 캔버스를 여는 것 — 캔버스를 선택하고 터미널 요약은 한 줄로 유지하세요.
- 상태 파일에서 캔버스 채팅을 구문 분석하는 것 — 필요한 모든 것은
await을 통해 도착합니다.
설계 노트 및 원본: docs/design/plan-canvas.md.