yasyf/design-doc

design-doc은(는) 무엇을 하나요?

gemini-4-argon이 모든 산문(요약, 일반어, 핸들, 개정 노트, 발행 텍스트 포함)을 작성하고 수정합니다. 세션은 gemini -m gemini-4-argon --skip-trust -p를 통해 사실과 규칙(작성 계약, slop-cop 규칙, 길이 제한)을 전달하고, 응답을 그대로 적용하며, 증거를 수집하고 결과를 직접 게시합니다. 산문 도우미는 gemini --skip-trust -p를 통해 동일한 모델을 호출하며, 대체 모델은 없습니다.

아키텍처 설계는 가정 위에 쌓인 결정의 스택입니다. 이 스킬은 설계를 대화(사용자가 모든 것을 결정)로 실행하고, 모든 주장이 가정, 결정, 그리고 이를 생성한 질문 라운드로 추적되는 문서를 렌더링합니다.

하나의 명령어로 기계적인 부분을 구동합니다:

TOOL="python3 ${CLAUDE_PLUGIN_ROOT}/skills/design-doc/scripts/design.py"
$TOOL scaffold --title <name>   # 이 설계 문서를 위한 새로운 ./<slug>/ 디렉토리
$TOOL scaffold --example        # ./tinyq/, 작은 작업 예제
$TOOL check <dir>               # 레지스터, 일반어, 다이어그램 소스 및 요약 데크 린트; 오류는 0이 아닌 종료 코드 반환, --strict는 게시를 차단하는 경고도 오류로 처리
$TOOL summary-text <dir>        # Markdown 형식의 데크, 각 패널은 ## 섹션; 게이트의 입력
$TOOL plainify <dir> [--only DQ3,A2] [--dry-run]
$TOOL glossary <dir>            # 산문이 사용하지만 용어집에 없는 용어를 후보 항목으로 반환
$TOOL build <dir>               # components/*.tsx를 components.js로 컴파일; components/ 디렉토리가 있는 문서에만 해당
$TOOL render-check <dir>        # 헤드리스 Chrome에서 모든 Mermaid 블록 렌더링; 구문 분석 오류 또는 페이지 예외 발생 시 실패
$TOOL pdf <dir>                 # 템플릿의 인쇄 스타일시트를 통해 문서를 <dir>/design-doc.pdf로 출력
$TOOL snapshot <dir> --note "…" --item "…" # 변경 사항 보기가 차이를 비교할 개정 버전을 스탬프; note는 독자용 제목, 각 --item은 하나의 변경 사항
$TOOL links <dir> [--fetch] [--missing] # 모든 결정 및 미해결 항목과 해당 pull request 링크 및 상태; --fetch는 GitHub에 각 링크가 병합되었는지 확인하고 차이를 보고, --missing은 아직 연결되지 않은 항목을 나열

1단계 전에 reference/method.md를, 5단계 전에 reference/writing.md를, 6단계 전에 reference/publish.md를 읽으세요 – method 파일은 라운드/레지스터 프로토콜, writing 파일은 음성 계약, publish 파일은 호스팅 흐름입니다. reference/schema.md는 JSON 파일의 필드별 계약입니다; 채워진 레지스터를 스키마 옆에 두고 싶다면 tinyq 예제를 스캐폴드하세요.

용어

• 레지스터(Register) — registers.json의 구조화된 목록으로, 항목에는 안정적인 ID(A# 가정, DQ# 결정, Q# 미해결 질문, V# 스파이크, c-<slug> 아키텍처 카드)가 있습니다.
• 라운드(Round) — 사용자에게 제시되는 하나의 보드로, qa-log.json에 원본 그대로 기록됩니다. 라운드는 모든 열린 분기를 한 번에 묻고, 각 분기는 design-doc.fork 블록으로 표시되며, 다른 것은 묻지 않습니다. 새로운 분기를 여는 답변은 다음 라운드를 시작하며, 다시 한 번에 모두 처리됩니다. qa-log.json은 라운드를 순서대로 기록하므로 이후 보드는 이전 답변에 의존할 수 있습니다.
• 대체(Supersession) — 변경된 결정은 새 항목을 얻고, 이전 항목은 s: "superseded"와 by 포인터를 받으며, 문서는 이를 "다음으로 대체됨"과 후속 항목의 제목으로 렌더링합니다. 제자리에서 편집되는 것이 없기 때문에 기록은 항상 읽기 쉽게 유지됩니다.
• 별표(Star) (★) — 하중을 지탱하는 가정을 표시하며, 이 가정이 실패하면 문서가 무효화됩니다.
• 스파이크(Spike) — 명명된 시간 제한 실험(V#)으로, (E)로 표시된 추정치를 측정된 숫자로 전환합니다.
• 임원 요약(Executive summary) — summary.html, registers.json 옆에 있는 직접 작성한 HTML 조각으로, 다른 것은 읽지 않는 독자를 위한 것입니다. 기본적으로 전체 화면 패널 데크이며, 설계가 하나의 아이디어와 하나의 그림일 때는 하나의 포스터입니다. 데이터로 구문 분석되지 않습니다. check는 모양, 단어 예산 및 인용을 린트합니다.
• 일반어(Plain twin) — 항목의 정확한 표현 옆에 있는 p 필드로, 해당 항목을 읽지 않을 사람에게 의미하는 바를 한두 문장으로 설명합니다. 문서는 기본적으로 일반어를 표시하고, 정확한 표현은 한 번의 토글만으로 볼 수 있습니다.
• 키(Key) 및 테마(Theme) — key: true는 문서가 카드로 여는 38개의 결정과 가정을 표시합니다. theme는 모든 항목을 설계의 35개 테마 중 하나로 분류하며, 0단계에서 명명되고 themes 맵에서 정의됩니다.
• 다이어그램(Diagram) — 시스템 다이어그램의 Mermaid 소스로, diagram 레지스터 키에 있습니다. 문서는 이를 렌더링하고, 독자는 패닝 및 호버링할 수 있으며, 요청 경로를 통해 단계별로 살펴볼 수 있습니다. diagram.overview는 개요 카드가 그리는 10노드 하위 집합이며, 전체 그래프는 한 번의 클릭으로 볼 수 있습니다. 손으로 그린 sysd.svg는 diagram.kind: "svg"로 유효합니다.
• 핸들(Handle) — 모든 결정, 가정, 미해결 항목, 아키텍처 카드 및 숫자 테이블의 h 필드: 독자가 부를 이름으로, 2~5단어입니다. 인용 및 칩 행은 핸들을 표시하고, ID는 호버 카드에 있습니다.
• 구성 요소(Component) — components 맵(dd.tabs, dd.before-after, dd.whatif, dd.steps, dd.timeline, dd.matrix, 두 비교 패널 그림 dd.flow 및 dd.lanes, 손으로 그린 시스템 맵 dd.system, 게시된 아키텍처 문서를 포함하는 dd.arch)에 선언된 대화형 그림으로, ID로 데크 또는 항목에 배치됩니다. components/ 아래의 TSX 파일은 build가 컴파일하는 탈출구입니다.
• 그림 설명(Figure brief) 및 비평(Critique) — 데크가 그려지고 읽히는 두 NOTES.md 섹션입니다. 설명은 그림이 그려지기 전에 작성되며, 그림당 다섯 줄입니다: 그림이 전달하는 요점, ID로 제공하는 결정, 요점을 전달하는 가장 작은 뷰, 생략하는 내용, 사용하는 실제 레이블. 처음 두 줄은 <figcaption>이 됩니다. 비평은 게이트 전에 작성되며, 패널, 그림, 테이블 및 통계당 한 행씩입니다: 제공하는 결정, 주장하는 내용, 독자가 남게 되는 질문, 고정 또는 삭제. check는 두 헤더 중 하나라도 누락되면 경고합니다.
• 링크(Link) — 결정, 미해결 항목 또는 결과 행의 links[] 항목: 이를 해결하는 pull request, 이슈, 커밋 또는 문서입니다. 미해결 항목 링크의 closes: true는 해당 항목을 종료하는 링크를 표시합니다. 문서는 각 링크를 GitHub 상태가 포함된 칩으로 표시하고, 각 미해결 그룹을 얼마나 많은 항목이 종료되었는지와 함께 표시합니다.
• 상태(Statuses): 결정은 resolved | superseded | open이며, 문서는 이를 결정됨, 대체됨, 아직 열림으로 렌더링합니다. 가정은 working | validate이며, 가정됨 및 확인 필요(문서 외부의 누군가가 확인해야 함)로 렌더링됩니다. 미해결 항목은 open | closed이며, 아직 열림 및 종료됨으로 렌더링됩니다. 병합된 closes 링크는 s가 그렇게 말하기 전에 항목을 종료합니다. 산문은 렌더링된 단어를 사용하고, JSON은 값을 사용합니다.

범위

이 스킬은 설계에서 멈춥니다. 출력은 결정 기록과 문서입니다. 구현 코드는 제안이 검토에서 살아남은 후에 시작되는 별도의 작업입니다. 네 가지 게이트가 기록을 정직하게 유지합니다:

• 설계 분기는 사용자가 결정합니다. 모든 분기는 라운드를 거치며, 한 옵션이 명백히 옳아 보일 때도 마찬가지입니다: 이유에 대한 기록은 절약된 교환보다 더 가치 있습니다.
• qa-log.json은 원본 그대로이며 추가 전용입니다. 답변의 철자를 정리하고, 내용을 변경하지 말며, 설명 전용 교환은 건너뛰십시오. 이것은 결정 로그이지 대화록이 아닙니다.
• 적대적 검토 산출물은 렌더링된 문서에 남지 않습니다. 그것이 유도한 결정만 전달됩니다. 결과 섹션은 자기 칭찬으로 읽히며 독자에게 아무것도 알려주지 않습니다.
• 문서에는 허영 카운트("27개 항목", "9개 스파이크 보류 중")가 포함되지 않습니다. 숫자는 시스템을 설명할 때 나타나며, 노력을 설명할 때는 나타나지 않습니다.

0단계 — 스캐폴드 및 진단

$TOOL scaffold --title <name>을 실행합니다. 모든 설계 문서는 자체 새 디렉토리에 있습니다 — scaffold는 ./<slug>/를 생성하고(다른 곳에 배치하려면 위치 인수로 명시적 경로 전달) 비어 있지 않은 대상은 거부하므로, 하나의 설계가 다른 설계의 파일이나 기존 프로젝트에 섞이지 않습니다. 아무것도 제안하기 전에 사용자에게 현재 시스템에 대해 인터뷰하십시오: 무엇이 존재하는지, 무엇이 문제인지, 그리고 이유가 무엇인지. 진단을 NOTES.md에 근본 원인으로 작성하십시오(증상이 아님: "내구성 지연 시간은 S3 지연 시간입니다", "쓰기가 느림"이 아님). 진단은 절대 보드에 올라가지 않습니다: NOTES.md에 직접 작성하고, 사용자는 렌더링된 문서에서 이를 검토하며, 그들의 모든 수정은 그들 자신의 말로 되접어집니다. 임원 요약이 의존하는 하나의 분류로 진단을 마무리하십시오: 오늘날 존재하는 시스템에 대한 변경(change) 또는 뒤에 요구 사항만 있는 완전 신규(net-new). 동시에 설계의 3~5개 테마를 명명하십시오("스토리지", "디스패치", "테넌시"): 이들은 결정과 가정이 분류되는 themes 맵이 되며, 진단이 명명할 수 없는 테마는 설계가 가지고 있지 않은 테마입니다. 잘못된 진단에 대해 설계하는 것은 이후 모든 단계를 낭비합니다.

종료 기준: 프로젝트 디렉토리가 존재합니다. 사용자가 렌더링된 문서에서 진단(변경 또는 완전 신규 및 테마 포함)을 읽고 동의합니다.

1단계 — 가정

첫 번째 라운드 전에 사용 가능한 스킬 목록에서 cc-present:present(/cc-present 보드 스킬)를 확인하고, 나열된 경우 Skill 도구로 호출하십시오. 인터뷰는 첫 번째 질문부터 라이브 보드로 실행되며, AskUserQuestion은 cc-present가 없는 경우의 대체 수단입니다. 이 플러그인은 자체 블록 팩과 함께 제공됩니다 — cc-present pack list를 실행하고 design-doc의 참조 조각을 읽으십시오. design-doc.fork 블록은 인터뷰 표면이며, 인터뷰 보드가 전달하는 유일한 블록입니다.

가정을 registers.json에 직접 작성하십시오. 보드가 이를 확인하거나 도전하지 않습니다. design-doc.claims 블록, 확인/도전 스윕 또는 레지스터 덤프를 사용자 앞에 두지 마십시오. 사용자는 렌더링된 문서에서 가정을 검토하며, 그들의 수정은 그들 자신의 말로 되접어집니다. 설계가 선택 없이는 진행할 수 없는 가정은 분기이며, 2단계 보드에 design-doc.fork 블록으로 들어갑니다. 진단 인터뷰, 코드 및 사용자가 이미 말한 것으로부터 근거 자료를 수집하십시오: 설계가 충족해야 하는 제약 조건, 규모 및 작업 부하에 대한 사실, 사용자가 믿지만 확인하지 않은 것. 각각은 상태가 working 또는 validate인 A# 항목이 됩니다. 하중을 지탱하는 가정에 별표를 표시하고, 각 validate 항목을 확인해야 하는 사람을 미해결 항목으로 기록하십시오. 사용자가 가정을 불안정하다고 표시하면, 그 표시는 항목에 들어갑니다. 사용자를 대신하여 해결하는 것은 레지스터의 요점을 무효화합니다.

종료 기준: 사용자가 렌더링된 문서에서 가정을 검토했고, 가정이 사용자가 아는 것을 다룹니다. $TOOL check가 깨끗합니다.

2단계 — 설계 라운드

질문 라운드로 설계하십시오. 인터뷰는 하나의 cc-present 보드로, 모든 열린 분기를 한 번에 묻고, 각 분기는 design-doc.fork 블록으로 풍부한 옵션과 함께 제시됩니다: 모든 옵션에 대한 결과, 장단점, 정확히 하나의 권장 사항, 그리고 열린 목록 탈출구. 보드는 분기 블록만 전달하고 다른 것은 없습니다. 분기 외의 모든 것은 결함입니다: design-doc.claims 블록, 확인/도전 스윕, design-doc.registers 덤프 또는 컨텍스트 블록. 분기 자체의 질문, 결과 및 장단점은 필요한 컨텍스트를 전달합니다. 새로운 분기를 여는 답변은 다음 보드로 가며, 같은 방식으로 구성됩니다.

라운드는 라이브 cc-present 보드에서 실행됩니다: 첫 번째 라운드 전(1단계 및 여기서 다시) 사용 가능한 스킬 목록에서 cc-present:present(/cc-present 보드 스킬)를 확인하고 Skill 도구로 호출하십시오 — 해당 지침은 보드 구성 및 푸시를 규율하며, 이후 모든 라운드는 보드를 통해 진행됩니다. 하나의 분기는 하나의 design-doc.fork 블록이며, 옵션은 결과를 인라인으로 전달하고 탈출구는 {defer: {title, why}}를 반환합니다: 인간이 미해결 질문의 이름을 지정하므로, Q#가 이름을 묻는 데 다른 라운드를 소비하지 않고 도착합니다. 팩이 없는 경우, 일반 choice 블록이 동일한 형태를 수동으로 전달합니다 — 모든 옵션에 대한 결과 설명, 정확히 하나는 "(권장)"으로 표시, 마지막 옵션 "열린 목록에 추가"는 실제로 Q#를 대기열에 넣습니다 — 그리고 AskUserQuestion은 최후의 수단 표면이며, cc-present:present가 스킬 목록에 없을 때만 사용됩니다. 보드 스킬이 존재하는 동안 설계 분기는 절대 AskUserQuestion을 통해 진행되지 않습니다. 각 분기를 사람이 즉시 답할 수 있는 평이한 질문으로 물으십시오("작업자는 어떻게 작업을 받아야 합니까?"). 분기가 해결하는 레지스터 ID는 블록의 decides 필드에 가거나 AskUserQuestion header 뒤에 오며, 질문 텍스트에는 절대 오지 않습니다. 옵션의 결과는 무슨 일이 일어나는지 말하며, 어떤 항목을 대체하는지 말하지 않습니다. 라운드는 인터뷰이지 설문조사가 아닙니다: 현재 초안의 결함을 지적하고, 사용자가 언급하지 않은 대안을 제안하며, 증거가 동의하지 않는 곳에서 반박하고, 스스로 결정하지 마십시오. 각 답변은 해결, 거부된 대안 및 라운드 번호와 함께 DQ#가 됩니다. 이후 라운드가 이전 결정을 변경하면 대체하십시오: 새 DQ#, 이전 결정에 by 포인터.

종료 기준: 열린 목록 외부에 결정되지 않은 분기가 없습니다. 모든 DQ#는 qa-log.json의 라운드로 추적됩니다.

3단계 — 적대적 검토

다듬기 전에 중간 초안을 공격하십시오. codex 플러그인 스킬을 사용할 수 있으면 사용하십시오. 그렇지 않으면 설계에 이해관계가 없고 회의적인 수석 엔지니어로 공격하라는 지침과 함께 새로운 컨텍스트 하위 에이전트를 생성하십시오: 정확성 버그, 누락된 실패 모드, 정당화되지 않은 숫자. 출력을 <reviewer>-review-<date>.md로 원본 그대로 저장하고, 각 결과를 findings 레지스터(데이터만, 렌더링되지 않음)에 인덱싱하고, 각각을 처리하십시오: 새 결정, 미해결 항목 또는 이유가 포함된 기록된 거부. 코드로 수정된 결과는 해당 행의 다섯 번째 요소로 pull request를 전달하며, links[] 항목과 동일한 형태입니다. 사용자의 결정이 필요한 결과는 다른 라운드와 마찬가지로, 검토자가 찾은 내용을 단어로 설명하는 질문이 있는 라운드가 됩니다. 결과 번호는 ... [잘림 - 원본과 일치하도록 의도적으로 잘림]

4단계 — 추정 및 스파이크

... [잘림 - 원본과 일치하도록 의도적으로 잘림]

5단계 — 산문

... [잘림 - 원본과 일치하도록 의도적으로 잘림]

6단계 — 게시

... [잘림 - 원본과 일치하도록 의도적으로 잘림]

7단계 — 유지 관리

... [잘림 - 원본과 일치하도록 의도적으로 잘림]