Design Session
시스템 설계가 기록되기 전에 소유자와 함께 설계를 생각해 봅니다. 소유자가 주도하고, 에이전트는 옵션을 확장하고, 각 옵션이 의미하는 바를 보여주며, 대화가 정직하게 진행되도록 합니다. 마지막 승격 단계에서 소유자가 무엇을 포함할지 선택할 때까지 어떤 것도 시스템 설계에 기록되지 않습니다.
시스템 설계가 존재하기 전, 마일스톤 계획 중, 또는 마일스톤 중간 등 언제든지 사용할 수 있습니다. 용어(시스템 설계, 추가 검사, 검토 가능 표면, settled/working, owner/proposed, 마일스톤, 스파이크, 임시 코드, 소유자 선호도, 두 번 무시 규칙)는 system-design 기술의 terms.md에 정의되어 있습니다. 여기에 정의된 대로 사용하십시오.
파일
<DocDir>/SystemDesign/
Overview.md 시스템 설계 (system-design); 승격 단계에서만 변경됨
Sessions/<date>-<Short_Topic>.md 이 기술의 임시 메모, 승격 단계 후 삭제됨
<date>는 YYYY-MM-DD 형식이고, Short_Topic은 2~3 단어를 Snake_Case로 표기합니다(예: 2026-11-01-Review_Import.md). 메모는 자유 형식입니다: ID, 상태, 동의 표시, 질문 제한이 없습니다. 소유자의 스케치, 고려된 형태와 다이어그램, 추적된 결과, 발견된 모순과 해결 방법, 스파이크 결과, 소유자가 선호하는 방향을 담습니다. 대화가 진행될 때마다 업데이트하여, 세션이 일찍 중단되더라도 파일에서 다시 시작할 수 있습니다.
워크플로우
1. 읽기, 그리고 소유자가 주도하도록 함
시스템 설계와 주제와 관련된 하위 시스템 문서, 로드맵의 현재 마일스톤, <DocDir>/Taxonomy.md, 프로젝트 규칙 파일(CLAUDE.md 또는 이에 상응하는 파일), 그리고 ${DANNY_SKILLS_STATE_DIR:-$HOME/.local/state/danny-agent-skills}/owner-preferences.md 파일(존재하는 경우)을 읽습니다. 이 주제에 대한 메모 파일이 Sessions/에 있으면 이어서 진행합니다. 그렇지 않으면 새로 생성하고 경로를 명시합니다.
소유자가 무엇을 그리고 있는지 묻고, 몇 줄로 스케치를 반영하고, 두 개 이상의 부분이 있을 때는 다이어그램을 제공합니다. 형태를 바꿀 수 있는 질문만 하고, 기본값으로 명시할 수 있는 것은 묻지 마십시오.
2. 대안 형태 제시
소유자의 스케치를 하나로 포함하여 2~3개의 형태를 제시합니다. 각 형태에 대해: plan-milestone 기술의 diagrams.md를 따르는 Mermaid 다이어그램(노드 레이블은 시스템 설계의 컴포넌트 이름을 정확히 사용, 새 부분은 sketched로 표시, 형태가 변경하는 내용은 touched로 표시), 프로젝트의 사례에 대한 동작 방식의 간단한 예제, 한 줄의 장점과 단점을 제시합니다. 그런 다음 하나를 추천하거나, "추천 없음"과 그 이유를 말합니다. 새 이름은 기능에 따라 지정합니다(terms.md, "Names and labels"). diagrams.md에 명시된 대로 각 다이어그램을 렌더링 확인합니다.
3. 결과 추적
소유자가 선호하는 형태에 대해, 무엇을 변경하는지 말합니다: 하위 시스템, 인터페이스, 데이터 모델, 검토 가능 표면(해당하는 경우 필드별로), 이름, 위협 및 개인정보 보호 섹션. 각 후속 마일스톤의 라인에 대해 추가 검사를 실행합니다: 구조 변경 없이 후속 마일스톤을 추가할 수 없는 경우, 어떤 인터페이스를 지금 결정해야 하는지 말합니다. 시스템 설계가 없거나 후속 마일스톤 라인이 아직 없으면, 마일스톤이 존재할 때까지 추가 검사를 건너뜁니다. 검사할 마일스톤을 임의로 만들지 마십시오. 형태가 변경할 모든 settled 항목의 이름을 지정합니다. settled 항목을 변경하는 것은 재계획 트리거입니다. 인터페이스 내부의 세부 사항은 결정하지 않은 상태로 두고, 세부 사항은 "실행 후 결정" 목록에 넣습니다.
4. 모순 찾기
소유자의 말이 이 세션의 이전 진술, settled 항목, 소유자 선호도, 프로젝트 규칙 또는 Taxonomy.md의 이름과 충돌하는 경우 명확히 말합니다. 양쪽을 인용하고 어느 쪽을 따를지 묻습니다. 답변을 메모에 기록합니다.
5. 일회성 스파이크 제안
무언가를 실행해야만 질문을 해결할 수 있을 때(충분히 빠른지, API가 이것을 반환하는지, 플랫폼이 그것을 할 수 있는지), 질문에 답하는 가장 작은 실행을 제안합니다: 무엇을 하는지, 어떤 결과가 어떤 방향을 가리키는지, 대략 얼마나 걸리는지. 소유자가 수락하는 경우에만 제품 코드 외부(임시 디렉토리 또는 폐기 가능한 브랜치)에서 빌드하고, 실행하고, 결과를 메모에 기록합니다. 코드는 폐기됩니다. 소유자가 유지하려는 경우, 6단계에서 임시 코드로 승격됩니다.
6. 승격
소유자가 완료했다고 말하거나 대화가 수렴되면, presenting-for-review.md 형식으로 시스템 설계에 입력될 수 있는 메모의 모든 항목을 나열하고, 각각 권장 결과를 함께 제시합니다:
settled로 승격 또는working으로 승격 및 재검토 메모("다음의 경우 재검토: …").- 연기 후속 마일스톤으로, 마일스톤 이름 지정.
- 삭제.
동일한 메시지에서 두 번 무시 규칙에 따라 소유자 선호도 라인을 제안합니다: 소유자가 이 세션에서 동일한 종류의 형태를 두 번 무시했거나, 기호를 직접 명시한 경우에만 해당합니다. 각 선호도 라인(선호도, 예시 하나, 날짜)은 교차 프로젝트 소유자 선호도 파일 또는 프로젝트 규칙 파일 중 어디에 넣을지 명시합니다. 단일 판결은 결정이지 선호도가 아닙니다. 이 기술의 작동 방식에 대한 피드백은 회고로 보내지며, 여기에 넣지 않습니다. 소유자의 표현(이름, 결과 텍스트, 인터페이스)의 각 항목에 대해, system-design 기술의 4단계 강화 제안을 동일한 메시지에서 한 번 수행합니다: 각 모호성을 나열하고 원본 옆에 강화된 버전을 표시합니다. 소유자가 수락, 편집 또는 유지합니다. 하나의 질문으로 끝냅니다.
소유자의 결정을 시스템 설계(overview-template.md)에 일반 편집으로 적용합니다:
| 승격된 항목 | 위치 |
|---|---|
| 컴포넌트 | Components 행(sketched, Build target, Agreement) 및 깊이 클래스만 있는 다이어그램 노드, touched는 안 됨 |
| 인터페이스 | Seams and interfaces 행 및 Agreement |
| 테이블, API 또는 공개 심볼 | 검토 가능 표면, 필드별, 마크 포함 |
| 엔티티 또는 관계 | 데이터 모델 |
| 이름 | Names, 그 다음 <DocDir>/Taxonomy.md, 나머지와 함께 세트로 검토 |
| 형태 간 선택 | Decisions 행: 다음 사용 가능 D ID, Kind choice, Agreement settled 또는 working (revisit if …), Why에 거부된 형태 이름 지정 |
| 세션에서 발견된 미지의 사항 | Risks 행 및 가장 저렴한 실험 |
| 후속 마일스톤 변경 | Scope and milestones 라인 및 Additive check 셀 |
| 소유자가 유지하는 스파이크 코드 | Provisional code 행 및 코드 내 PROVISIONAL 마커 |
| 연기된 구조적 항목 | Open questions 라인, 대기 중인 마일스톤 이름 지정, 예: "Q4 (parked until M3, record changes): …" |
| 연기된 세부 사항 | "decide after it runs" 목록, 이를 해결할 마일스톤 아래 |
동의 표시는 템플릿을 따릅니다: 소유자가 작성하거나 편집한 항목은 owner로 읽힙니다(예: settled · owner). 소유자가 변경 없이 수락한 항목은 proposed 표시를 하지 않습니다. 새 ID는 문서의 시퀀스를 계속하며 재사용되지 않습니다. 합의된 항목의 변경은 결정 로그를 통해 이루어지며, 조용한 편집으로 이루어지지 않습니다. 승격된 항목이 settled 항목(예: 인터페이스)을 변경하거나 소유자 요청이 현재 마일스톤에 구조를 추가하는 경우, 재계획이 필요하다고 명확히 말하고, 아래 커밋 후에 핸드오프 노트를 작성하여 /rung이 이후 세션에서 재계획을 라우팅하도록 합니다: <DocDir>/Handoff/replan-<date>.md 파일에 Route: replan, Model: opus, Waiting on: re-plan after the design session on <topic>, Date:, 그리고 변경된 항목과 커밋을 본문에 포함합니다(handoff.md). 삭제된 항목은 기록되지 않습니다. git 히스토리의 메모 파일이 이를 유지합니다. 수락된 선호도 라인은 소유자가 선택한 파일에 씁니다.
아직 시스템 설계가 없는 경우, 승격된 항목을 템플릿 헤더(Status: draft)와 해당 항목이 채우는 섹션만 있는 새 Overview.md에 씁니다. system-design이 이를 이어받아 진행합니다.
커밋: 명시적 경로로 스테이징하여 시스템 설계, Taxonomy.md, 변경된 경우 프로젝트 규칙 파일, 메모 파일을 Design session: <topic> 메시지로 커밋하여 히스토리가 메모를 유지하도록 합니다. 그런 다음 git rm으로 메모 파일을 삭제하고 Remove design session notes: <topic> 메시지로 커밋합니다. step 이벤트를 skill design-session 1.0.1 및 kind design-session(다른 필드는 tasklist-run의 메트릭 로그에 있음)으로 기록하고, 승격을 위해 제안한 항목 수(proposed, accepted (변경 없음), edited, rejected)를 포함합니다.
무엇이 변경되었고 다음 단계가 무엇인지 말하는 간단한 문장으로 끝낸 다음, Next: /rung을 추가하고, 해당 단계에 Opus가 필요한 경우(아직 합의해야 할 시스템 설계, 마일스톤 계획, 또는 6단계에서 필요하다고 명시된 재계획) (Opus: /model opus)를 추가합니다.
소유자가 승격 전에 중단하는 경우, 메모 파일을 커밋되지 않은 상태로 두고 경로를 말합니다. 해당 주제에 대한 다음 디자인 세션이 이 파일에서 이어집니다.
연결된 파일 또는 기술이 누락된 경우
연결된 파일이 없는 경우 중단하지 마십시오: 여기서 최소한을 사용하고, 무엇이 누락되었는지와 설치 방법(claude plugin install project-planning@danny-sung-agent-skills, 또는 npx skills add dannys42/agent-skills --skill <skill-name>을 같은 skills 디렉토리에 실행하여 상대 링크가 해결되도록 함)을 한두 줄로 한 번 말합니다.
terms.md없음:settled는 유지되어야 함을 의미합니다.working은 시작하기에 충분하며, 무엇이 재검토하게 만드는지 이름을 지정합니다.owner항목은 소유자의 말이고,proposed는 에이전트의 말입니다. 추가 검사는 각 후속 마일스톤을 구조 변경 없이 추가할 수 있는지 묻습니다.diagrams.md없음: Mermaidflowchart, 모든 레이블 인용, 레이블은 컴포넌트 이름, 깊이당 하나의 클래스(sketched점선,designed얇은 실선,built굵은 실선).presenting-for-review.md없음: 중요한 항목 먼저(최대 5개, 되돌리기 어렵거나 영향 범위가 넓은 것), 각각 옵션, 간단한 예제, 장점과 단점, 추천; 하나의 질문으로 끝냄.overview-template.md없음: 시스템 설계의 기존 섹션으로 승격, 테이블 및 표시와 일치시킴.
판단 호출
- 소유자가 주도합니다. 형태와 결과를 제시하십시오. 심문하거나 자신이 선호하는 방향으로 유도하지 마십시오. 형태를 바꾸지 않는 질문은 할 가치가 없습니다.
- 자유롭게 탐색하고, 좁게 승격하십시오. 세션에서 무엇이든 논의될 수 있지만, 구조만 시스템 설계에 입력됩니다: 하위 시스템, 인터페이스, 데이터 모델, 검토 가능 표면, 이름, 결정 및 위험. 내부 세부 사항은 제외됩니다.
- 스파이크는 논쟁보다 낫습니다. 소유자와 에이전트가 짧은 실행으로 해결될 수 있는 사실에 대해 동의하지 않는 경우, 논쟁 대신 실행을 제안하십시오.