C4 Plan
사람은 계획의 구조와 경계를 이해하고, AI는 채팅에서 승인된 이후에 실행합니다. 이 스킬은 계획을 대체하지 않고, 계획의 시각적 계층과 실행을 위한 브리프를 생성합니다.
또한 현재 시스템 문서화 (kind: system)에도 사용됩니다: 동일한 다이어그램과 흐름을 사용하지만 상태, 단계, 승인 절차는 없습니다. 5절을 참조하세요.
채팅이 진리의 원천입니다. 뷰어는 계획만 표시하며, 사람은 그곳에서 아무것도 편집하지 않습니다. 질문이나 변경 요청은 댓글로(또는 채팅에 붙여넣어) 전달되고, AI는 채팅에서 응답하며 모든 변경은 YAML을 통해 이루어집니다.
AI는 절대 HTML을 작성하거나 URL을 수동으로 생성하지 않습니다. AI는 YAML을 작성하고, 스크립트가 유효성을 검사한 후 링크와 브리프를 생성합니다.
계획 ─► arch.yaml ─► 인코딩 ─► 링크 ─► 사람이 보고 댓글 ─► AI가 YAML 조정 ─► 채팅에서 승인 ─► 브리프 ─► 실행
스크립트: python3 <dir-da-skill>/scripts/arch_url.py (stdlib + PyYAML만 사용; jsonschema는 선택 사항).
1. 계획에서 arch.yaml 생성하기
계획 파일 옆에 <nome-do-plano>.arch.yaml로 저장하세요. 스키마: schema/arch.v1.json. 전체 예제: examples/pix.arch.yaml.
규칙:
- 계획의 아키텍처이지, 전체 시스템의 아키텍처가 아닙니다. 계획이 생성, 변경 또는 제거하는 요소와 이해에 필요한 최소한의 컨텍스트(누가 호출하고, 누가 호출되는지)를 포함하세요. 전체 시스템을 모델링하지 마십시오.
status:new/changed/removed/unchanged(기본값). 컨텍스트 요소는unchanged로 남깁니다.- C4 계층 구조:
person,system,external은 최상위에;container,database,queue는system내부(또는 최상위)에;component는container,database(테이블, 마이그레이션) 또는queue(이벤트) 내부에;code는component내부에만 위치합니다. - 계획이 생성하거나 변경하는 모든 것은 코드까지 열려야 합니다.
status가new/changed인 모든system,container,database,queue및component는children을 가지며,code까지 내려가야 합니다(누락 시validate가 경고). 변경되지 않는 것은 닫힌 상태로 유지되며 컨텍스트로 간주됩니다. - 레벨 4 (
code): 계획이 생성하거나 변경하는 파일, 클래스, 모듈 또는 함수이며path가 채워져야 합니다. 이미 존재하지만 변경되는 파일은status: changed입니다. 변경되는 내용만 나열하고, 컴포넌트의 전체 코드는 나열하지 마십시오(컴포넌트당 2~4개면 충분합니다). - 관계는 가장 구체적인 요소를 연결합니다(code→code가 가능한 경우). 뷰어는 상위 수준으로 집계합니다.
steps: 계획의 각 단계당 하나씩, 동일한 순서와 제목을 사용합니다.touches= 해당 단계가 생성하거나 변경하는 요소들입니다.flows: 계획 이후 시스템이 작동하는 방식을 나타냅니다(steps는 구축 순서,flows는 실행 순서). 1~3개의 흐름: 주요 경로와 가장 중요한 실패 경로(예: "고객이 PIX로 결제", "QR 코드 만료"). 각hops[]는{from, to, label}이며, 기존 관계를 따라야 하고 해당 방향 또는 응답을 위한 반대 방향으로 설정됩니다. 가장 구체적인 요소(code)를 사용하고,label은 관계 이름이 아니라 발생하는 작업(예: "PSP를 호출하기 전에 txid 저장")으로 작성합니다. 뷰어는 각 홉의 레벨까지 자동으로 내려갑니다.constraints: 구현이 반드시 준수해야 하는 사항으로, 검증 가능한 규칙(예: "txid별 멱등성", "추가 마이그레이션, 테이블 잠금 없음")이지 설명이 아닙니다. 중요한 결정이 있는 곳(계약, 외부 시스템 경계, 보안, 데이터, 마이그레이션, 핵심 비즈니스 규칙)에 배치하세요. 제약 조건이 없는 것은 실행 시 AI의 재량에 맡깁니다.- 저장소에 계약이 존재하는 경우
relations[].contract에서 참조하세요.
2. 유효성 검사 및 링크 제공
python3 scripts/arch_url.py encode <plano>.arch.yaml
- 오류: YAML을 수정하고 다시 실행하세요. 통과하지 못한 링크는 제공하지 마십시오.
- 경고: 합당한 경우 수정하세요(예: 코드까지 열리지 않은 새 요소).
- 링크를 한 줄로 사람에게 제공하고, 계획이 변경하는 내용에 대한 간략한 요약(예: "새 요소 3개, 변경된 요소 2개")을 함께 전달하세요. C(또는 댓글)를 누르고, 카드를 클릭하여 질문하거나 변경을 요청할 수 있으며, 승인은 여기 채팅에서 이루어짐을 알리세요.
뷰어: encode는 게시된 버전 https://gustavorana25.github.io/c4-model-skill/ 에 대한 링크를 생성합니다(정적 페이지이며, 계획은 #hash에 포함되어 서버로 전송되지 않습니다). $C4PLAN_VIEWER_URL로 호스트를 변경할 수 있으며, --local은 로컬 빌드 viewer/dist/index.html을 사용합니다(뷰어 자체 변경 사항 테스트 전용).
2b. 내장 브라우저가 있는 경우: 페이지 수신 대기
브라우저 도구(Claude Code의 브라우저 패널, Cursor의 브라우저, Chrome의 Claude)가 있다면, 링크만 제공하지 말고 거기서 링크를 열고 사람이 계획을 보는 동안 페이지를 수신 대기하세요.
채팅이 진리의 원천입니다. 페이지는 단지 바로가기일 뿐입니다: 사람이 하나 이상의 카드를 지정하고 댓글을 달면, AI는 채팅에서 응답하며 페이지에서 절대 응답하지 않습니다. AI가 페이지에서 변경하는 유일한 것은 대화가 구조를 변경할 때 load()를 사용하여 계획을 업데이트하는 것입니다.
encode가 생성한 링크를 있는 그대로 여세요. 이미 https://입니다. (--local을 사용하는 경우 viewer/dist/를 http://로 제공하세요(예: python3 -m http.server). 일부 내장 브라우저는 file:// 링크의 #hash를 무시합니다.)
페이지는 window.c4plan을 노출합니다(브라우저 JavaScript 도구로 실행).
| 호출 | 기능 |
|---|---|
await c4plan.next(30000) | 최대 30초 동안 다음 이벤트를 기다립니다. 이벤트 또는 null을 반환합니다. 최대 시간은 40초입니다(도구가 ~45초에서 중단). |
await c4plan.state() | 현재 상태: url, plan, focus(열린 수준), selected(사람이 보고 있는 항목), idleMs(페이지와 상호 작용하지 않은 시간), doc. |
c4plan.load(urlOuHash) | 페이지를 다시 로드하지 않고 새 버전의 다이어그램으로 전환합니다. |
c4plan.stop() | 수신 대기를 중단했음을 페이지에 알립니다. |
next()의 이벤트:
{event:"comment", targets:[{id,name}], view, text}: 사람이 이러한 요소에 대해 댓글을 남겼습니다(없음, 하나 또는 여러 개 가능,view는 열린 수준). 채팅에서 응답하고, 이름으로 시작하세요: "API Pix 및 결제 대기열 관련: …". 변경 요청인 경우 YAML을 수정하고,encode를 실행하고,load(새로운링크)를 호출한 후 채팅에서 변경 사항을 알리세요. 그런 다음 계속 수신 대기합니다.{event:"stop", reason:"idle"}: 사람이 10분 동안 페이지와 상호 작용하지 않아 수신 대기가 자동으로 종료되었습니다. 중단 문구(3단계)를 말하고 루프를 종료합니다.
루프:
- 시작하기 전에 채팅에 한 줄로 말하세요: "브라우저에서 다이어그램을 열었고, 사용자가 조작하는 동안 수신 대기 중입니다. C(또는 댓글)를 누르고, 카드를 클릭하고, 작성하세요: 제가 여기서 응답합니다. 모든 것이 준비되면 여기서 승인한다고 알려주세요." 이 알림이 없으면 사람이 페이지를 조작해도 채팅에 아무것도 나타나지 않아 상황을 이해하지 못합니다.
await c4plan.next(30000)을 반복하고 각 이벤트를 처리합니다.null은 "아직 아무것도 없음"을 의미합니다: 다시 호출하고 채팅에 언급하지 마십시오. 수신 대기는 사람이 페이지와 상호 작용하는 동안 지속됩니다(각 클릭, 키 입력 또는 스크롤이 타이머를 재설정). 종료는 페이지가stop으로 결정합니다.stop이 도착하면 중단합니다.stop에서 채팅에 말하세요: "다이어그램 수신 대기를 중단했습니다(페이지가 유휴 상태). 원할 때 채팅에 댓글을 남기거나, 다시 수신 대기하도록 요청하세요." 다른 이유로 먼저 중단해야 하는 경우c4plan.stop()을 호출하고 동일한 내용을 말하세요.- 수신 대기 중 사람이 채팅에 메시지를 보내면 루프가 종료됩니다: 메시지에 응답하세요. 그런 다음
(await c4plan.state()).idleMs를 읽으십시오: 10분 미만이면 아직 페이지에 있는 것이므로 다시 알리지 않고 루프로 돌아가십시오. 승인하면c4plan.stop()을 호출하고 3단계로 진행합니다. - 사람이 채팅에서 "이것" 또는 "이 요소"에 대해 질문하면
state().selected를 읽어 무엇을 말하는지 파악합니다. - AI가 수신 대기하지 않을 때 댓글 버튼은
Sobre "API Pix" (pix-api) no diagrama: …와 같은 텍스트를 복사하여 사람이 채팅에 붙여넣을 수 있도록 합니다. 괄호 안의 id는 YAML의 것입니다.
3. 사람이 채팅에서 승인할 때
사람만 승인할 수 있으며, 채팅에서만 가능합니다("승인", "계속 진행", "좋아, 실행"). 침묵, 수신 대기 종료 또는 댓글 부재는 승인이 아닙니다.
<plano>.arch.yaml에approved: true를 표시하고 파일에서 브리프를 생성합니다:python3 scripts/arch_url.py brief <plano>.arch.yaml -o <plano>.arch.md- 대화로 인해 첫 번째 링크 이후 변경된 사항(제약 조건, 구조, 흐름)을 몇 줄로 요약합니다.
- 계획에
<plano>.arch.md에 대한 참조를 추가하고 실행을 진행합니다.
사람이 뷰어 링크(예: 일반 브라우저에서 열린)를 붙여넣는 경우, 이는 보기 전용입니다: 유효한 버전은 AI의 <plano>.arch.yaml입니다.
4. 브리프를 준수하여 실행하기
<plano>.arch.md는 실행 중에 필수입니다:
- 구조(요소, 관계, 흐름)와 모든 제약 조건을 따르세요. 구현으로 인해 구조를 변경하거나 제약 조건을 위반해야 하는 경우 중단하고 질문하세요.
- 참조된 계약(
contract)은 묻지 않고 변경하지 마십시오. - 제약 조건 외부에서는 가장 간단한 방법을 선호하고 기존 코드의 패턴을 따르세요.
- 사람이 채팅에서 요청한 내용이 AI의 원래 제안보다 우선합니다.
- 마지막으로, 구현된 내용을 YAML과 비교하고 차이점(예상치 못한 새 컴포넌트, 관계 외부의 종속성, 변경된 계약)을 보고하세요.
5. 현재 시스템 문서화 (kind: system)
요청이 기존 항목을 이해하거나 문서화하는 것("아키텍처 문서화", "이 시스템 작동 방식", 온보딩)인 경우, 계획이 없습니다: 저장소를 읽고 kind: system으로 동일한 YAML을 생성하세요. 전체 예제: examples/loja.arch.yaml.
version: 1
kind: system
title: 온라인 상점
description: 시스템이 수행하는 작업에 대한 한두 문장.
작성 방법:
- 작성하기 전에 먼저 읽으십시오. 진입점(라우트, 핸들러, 컨슈머, 작업), 매니페스트(
package.json,docker-compose, 인프라), 마이그레이션 및 외부 서비스 클라이언트를 통해 컨테이너, 데이터베이스, 대기열 및 외부 항목을 파악할 수 있습니다. 코드에 표시되지 않는 부분을 임의로 추가하지 마십시오. 불확실한 것이 있으면 채팅에 문의하세요. status,steps,approved는 사용하지 마십시오. 모든 것은 현재 시스템 상태입니다(validate가 남아 있으면 경고).- 흐름이 핵심입니다. 2~4개: 비즈니스에 가장 중요한 경로, 주요 백그라운드 작업 및 가장 일반적인 실패 사례입니다. 이를 통해 새로 들어오는 사람이 시스템을 이해합니다.
- 깊이: 흐름이 통과하는 부분만
code까지 내려가고 실제path를 사용하십시오(파일이 존재하는지 확인). 나머지는container또는component에서 닫힌 상태로 유지됩니다. constraints는 작업자가 알아야 할 가이드라인이 됩니다(멱등성, 각 테이블에 쓸 수 있는 사람, 변경되지 않는 계약).- 관계 및 흐름은 계획(1절)과 동일한 규칙을 따릅니다.
제공: encode는 계획과 마찬가지로 링크를 생성합니다. 시스템 구성("컨테이너 5개, 외부 2개, 흐름 2개")을 한 줄로 말하고, 흐름 탭에서 흐름을 따라가며 C로 질문할 수 있음을 알리세요. 브라우저가 있으면 페이지를 수신 대기하십시오(2b절): 댓글은 질문(채팅에서 응답) 또는 문서 수정(YAML에 적용하고 load()로 다시 로드)입니다.
저장소에 버전 관리 가능한 텍스트를 위해 brief는 Markdown 문서(요소, 관계 및 흐름)를 생성합니다:
python3 scripts/arch_url.py brief docs/arquitetura.arch.yaml -o docs/arquitetura.md
나중에 이 시스템에 대한 계획은 이 YAML에서 시작할 수 있습니다: 복사하고, kind를 plan으로 변경하고, 변경 사항을 status로 표시하세요.