plan-canvas

Plan Canvas

계획 및 시각적 아티팩트의 검토 루프: 당신이 아티팩트를 작성하면, 사용자는 브라우저에서 이를 검토합니다 — 정확히 의도한 요소에 주석을 달고, 채팅하며, 계획 승인 / 변경 요청 판정을 내립니다 — 그동안 당신은 단일 CLI 호출에서 차단되어 그들의 피드백을 JSON으로 반환받습니다.

lavish-axi에서 영감을 받았으며; /plan 확인 게이트 주위에 ECC-네이티브로 재구축되었고, 의존성이 전혀 없습니다.

사용 시기

• 방금 계획 아티팩트(/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 루프이므로, 모델 및 하네스에 구애받지 않습니다: 쉘 명령을 실행하고 표준 출력을 읽을 수 있는 모든 에이전트(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단계를 분할했습니다. 확인해보세요."

모든 사용자 메시지는 캔버스에서 답변을 받아야 합니다. "지금 위험 테이블을 다시 작성 중입니다."와 같은 한 줄짜리라도 마찬가지입니다. 채팅 패널에서의 침묵은 캔버스가 고장난 것과 구분할 수 없으며, 이것이 바로 이 루프가 방지하고자 하는 실패입니다. 터미널에서만이 아니라 캔버스에서 답변하십시오.

작업하는 동안 활동 표시기로 채팅을 정직하게 유지하십시오:

# 애니메이션 "agent is thinking..." 버블; 긴 작업 중에 새로 고침
ecc-plan-canvas typing <file> --state thinking
# 답변이 도착하기 직전에 "agent is typing..."으로 전환
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에서 브라우저로 로드됩니다; 사용할 수 없는 경우(오프라인), 블록은 소스 코드를 표시하므로 검토가 차단되지 않습니다. 오프라인 환경에서는 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.