方案设计与实施工作流

설계 및 구현 워크플로우

핵심 개념

먼저 충분히 논의한 후, 코드를 작성하세요. 이 워크플로우는 '생각'과 '실행'을 강제로 분리합니다:

• 논의 단계: 대화만 하고, 코드는 작성하지 않으며, 모든 결론은 커뮤니케이션 문서에 기록됩니다.
• 설계 단계: 합의된 내용을 설계 문서로 정리합니다. 이것이 유일한 사실 출처입니다.
• 구현 단계: 설계 문서를 기반으로 구현 문서를 생성하고, 단계별로 실행합니다.

논의가 끝나지 않았거나, 사용자가 명시적으로 '구현을 시작해도 된다'고 말하지 않았다면 절대 코드를 건드리지 않습니다. 양측이 만족할 때까지 의문이 남아있으면 계속 논의합니다.

문서 디렉토리 구조

프로젝트 루트 디렉토리의 docs/design/ 아래에 고정적으로 저장됩니다. 각 태스크는 독립적인 하위 폴더를 가집니다:

프로젝트 루트/
└── docs/design/
    ├── README.md              ← 전역 태스크 개요 (다중 태스크 진입점, 가장 먼저 읽음)
    ├── 01-사용자-인증-모듈/
    │   ├── 00-태스크-상태.md      ← 컨텍스트 간 메모리 앵커
    │   ├── 01-커뮤니케이션-과정.md
    │   ├── 02-설계.md          ← 수락 기준 포함
    │   ├── 03-구현.md
    │   └── 04-테스트.md          ← 테스트 케이스 세트 (구현 계획 단계에서 생성)
    └── 02-결제-리팩터링/
        └── ...

명명 규칙:

• 태스크 폴더: 전역적 증가 두 자리 숫자 + 태스크 이름, 예: 01-사용자-인증-모듈, 02-결제-리팩터링. 숫자는 태스크 전체에 걸쳐 연속적으로 증가하여 생성 순서와 정렬 순서가 일치하도록 보장합니다.
• 태스크 내 문서: 고정된 단계 숫자 접두사: 00-태스크-상태 / 01-커뮤니케이션-과정 / 02-설계 / 03-구현 / 04-테스트. 고정 접두사 덕분에 어떤 태스크에서든 동일한 유형의 문서를 한눈에 찾을 수 있습니다.

처음 태스크에 진입할 때 번호를 결정하는 방법: docs/design/ 아래에 있는 기존 폴더의 최대 번호를 확인하고, +1을 새 태스크 번호로 사용합니다. 디렉토리가 없으면 01부터 시작합니다.

새 대화의 첫 번째 단계 (다중 컨텍스트 메모리 메커니즘)

이 워크플로우는 여러 대화 컨텍스트에 걸쳐 실행될 수 있습니다. 새 대화마다 코드를 대규모로 다시 읽거나 기억을 잃는 것을 방지하기 위해 다음 순서로 컨텍스트를 복원해야 합니다:

1. docs/design/README.md 읽기 — 전역 태스크 개요를 확인하여 어떤 태스크가 있고, 각각 어떤 단계에 있는지 확인합니다. 사용자가 이미 태스크를 지정했다면 해당 태스크로 바로 이동합니다.
2. 00-태스크-상태.md 읽기 — 현재 태스크의 메모리 앵커로, 다음에 무엇을 해야 하는지 확인합니다.
3. 현재 단계에 해당하는 문서 읽기 (예: 설계 단계에서는 02-설계.md 읽기, 구현 단계에서는 03-구현.md 읽기).
4. 컨텍스트 복원의 첫 번째 수단으로 코드를 읽지 말고, 확인이 필요할 때만 코드를 읽습니다.

00-태스크-상태.md는 다음을 유지해야 합니다: 태스크 한 줄 설명, 현재 단계, 주요 결정 요약, 할 일 및 질문, 문서 색인, 컨텍스트 전환 로그, 변경 기록 (수정 및 롤백 포함, 아래 '구현 단계의 변경' 참조).

워크플로우의 4단계 및 해당 문서

1단계: 논의 (출력 → 커뮤니케이션 과정 문서)

트리거: 사용자가 새로운 요구 사항, 새로운 기능, 새로운 모듈을 제안하거나 기존 설계에 대해 질문하고 논의하려고 할 때.

행동 제약:

• 이 단계에서는 오직 논의만 하고, 어떤 비즈니스 코드도 작성하지 않습니다.
• 의미 있는 교류(주요 결정 사항, 기각된 대안, 합의된 내용)가 있을 때마다 01-커뮤니케이션-과정.md에 추가로 기록합니다.
• 미결 질문 추적: 01-커뮤니케이션-과정.md 상단에 '현재 미결 질문' 목록을 유지합니다. 각 논의가 끝나기 전에 이 목록을 업데이트합니다 — 어떤 물음표가 아직 남아 있는지, 어떤 것이 새로 생겼는지, 어떤 것이 이미 종결되었는지. 설계 단계로 진입할 수 있는지 여부를 판단하는 직접적인 근거는 이 목록이 비어 있는지 여부입니다. 이는 논의 수렴 과정을 시각화하여, '충분히 논의했다'는 막연한 느낌에 의존하지 않도록 합니다.
• 논의는 여러 번, 여러 대화에 걸쳐 진행될 수 있습니다.
• 사용자가 '됐어요', '이걸로 정하죠', '설계를 시작하죠'라고 표현하고 미결 질문 목록이 비어 있으면 2단계로 진입합니다.

논의를 계속해야 하는 경우: 해결되지 않은 설계 질문, 기술 선택에 대한 이견, 명확하지 않은 경계가 있는 한 1단계에 머물러 결과물을 축적합니다. 모호한 가정을 가지고 설계로 넘어가기보다 한 번 더 질문하는 것이 낫습니다.

2단계: 설계 (출력 → 설계 문서)

트리거: 논의가 합의에 도달하고, 미결 질문 목록이 비어 있으며, 사용자가 설계를 확정하는 데 동의했습니다.

행동 제약:

• 커뮤니케이션 과정의 결론을 구조화된 02-설계.md로 정리합니다. 설계 문서는 유일한 사실 출처입니다.
• 설계 문서는 가능한 한 완전해야 합니다: 전달 시점에는 확정되고 실행 가능한 계획이어야 하며, '미정', '구현 단계에서 결정'과 같은 잔여물이 없어야 합니다. 완전성은 두 가지를 통해 보장됩니다 — 하나는 반복적인 의사소통으로 질문을 철저히 하는 것이고, 다른 하나는 기존 코드를 읽어 모든 의존성(인터페이스 형태, 테이블 구조, 호출 방식 등)의 기존 구현 사실을 확인하는 것입니다. '설계 단계에서는 논의만 하고 코드를 작성하지 않는다'는 제약은 비즈니스 코드에 적용됩니다. 설계를 위해 기존 코드를 읽고 현재 상태를 확인하는 것은 설계 조사에 속하며, 제약을 위반하지 않습니다. 설계 단계에서는 시간을 더 들여 반복적으로 다듬는 것이 좋으며, 결함을 가지고 구현 단계로 넘어가지 마십시오 — 결함은 구현 단계에서 재작업이나 편차로 이어집니다.
• 수락 기준은 설계의 일부입니다: 설계 문서는 '무엇을, 왜'뿐만 아니라 '어느 정도까지 해야 요구 사항을 충족하는지' — 즉 추상적인 수락 기준(규칙 수준, 예: '고위험 단어는 반드시 차단하고, 게시물은 데이터베이스에 저장하지 않음')을 작성해야 합니다. 수락 기준은 요구 사항의 경계를 정의하며, 설계 완전성의 마지막 단계입니다. 수락 기준이 없는 설계 문서는 '완료'에 대한 객관적인 정의가 없는 것과 같습니다. 구체적인 테스트 케이스(인스턴스 수준)는 설계 문서에 작성하지 않고, 04-테스트.md에 구현 계획 단계에서 수락 기준을 케이스로 변환하여 작성합니다.
• 설계 변경 기록: 설계 문서 내에 '설계 변경 기록' 블록을 유지하고, 중요한 변경이 있을 때마다 한 줄(시간, 변경 내용, 변경 이유)을 기록합니다. 이는 01-커뮤니케이션-과정.md과 상호 보완적입니다 — 커뮤니케이션 과정은 흐름 기록이고, 설계 문서는 결론이며, 변경 기록은 결론의 진화 내역입니다. 이는 '설계 변경은 설계 문서를 수정하고 구현 문서를 수정하지 않는다'는 철칙이 역사를 잃지 않고 실행 가능하도록 합니다.
• 설계 문서가 완료되면 00-태스크-상태.md를 업데이트하여 '설계 완료, 구현 대기 중'으로 표시하고, docs/design/README.md의 태스크 단계도 동기화하여 업데이트합니다.

3단계: 구현 계획 (출력 → 구현 문서)

트리거: 설계 문서가 확정되었습니다.

행동 제약:

• 설계 문서를 기반으로 03-구현.md을 생성하여 계획을 실행 가능하고 체크 가능한 단계 목록으로 분해합니다.
• 동시에 설계 문서의 '수락 기준'을 구체적인 테스트 케이스로 변환하여 04-테스트.md를 생성합니다: 케이스는 수락 기준의 인스턴스화입니다 (예: 수락 기준 '고위험 단어는 반드시 차단' → 케이스 '고위험 단어가 포함된 텍스트 입력, 40901 오류 반환 및 게시물 미저장 예상'). 케이스는 네 가지 계층으로 나뉩니다: 기능(T-F), 예외(T-EX), 회귀(T-R), 인터페이스(T-API). 번호 형식은 T-{유형}-{두 자리 숫자}이며, 템플릿은 assets/test.md를 참조하십시오.
• 구현 문서는 '방법', 테스트 문서는 '무엇을 테스트하고, 예상 결과는 무엇인지', 설계 문서는 '무엇을, 왜'입니다. 세 가지의 역할이 다르므로 설계 세부 사항을 구현 문서에 그대로 복사하지 말고, 구현 문서에 설계 변경을 포함시키지 마십시오.
• 구현 문서는 순수한 단계 분해이며, 각 단계는 단지 '설계 문서의 특정 부분을 구현'하는 것입니다. '설계 완성'의 책임을 지지 않습니다. 단계를 분해하는 과정에서 어떤 단계를 수행하려면 먼저 '인터페이스 형태 확인', '설계 재작성', '필드 결정'이 필요하다는 것을 발견하면, 이는 설계 단계가 완료되지 않았음을 의미합니다 — 이 경우 2단계로 돌아가 설계를 완성해야 하며, 구현 문서에 '설계 보완' 단계를 넣어서는 안 됩니다. 한마디로: 구현 문서에는 '코드를 읽어 설계를 확정하는' 성격의 동작이 전혀 없어야 하며, '정해진 설계에 따라 구현하는' 동작만 있어야 합니다.
• 구현 문서 내의 테스트 동작은 케이스 번호만 참조하고, 케이스 내용을 반복해서 작성하지 않습니다. 각 단계 완료 후 검증해야 할 사항은 '케이스 T-XX-XX 대조 검증'으로 작성하고, 케이스 자체는 04-테스트.md에 집중시킵니다.
• 구현 단계는 대단계와 소단계의 두 계층으로 나뉘며, 각각 독립적인 완료 표시가 있어야 합니다.
• 구현 문서가 완료되면 00-태스크-상태.md를 업데이트하여 '구현 대기 중'으로 표시합니다.

4단계: 구현 (구현 문서의 단계 실행)

트리거: 사용자가 '구현 시작', '해 보자', '문서대로 진행'이라고 말합니다.

행동 제약:

• 03-구현.md의 단계를 엄격히 따라 진행하며, 각 단계를 완료할 때마다 문서에서 표시를 업데이트하고 결과를 간략히 기록합니다.
• 각 단계를 완료할 때마다 04-테스트.md에서 해당 단계가 참조하는 케이스와 대조하여 검증합니다. 케이스가 실패하면 해당 단계는 완료된 것으로 간주되지 않으며, 문제를 파악합니다(구현 버그인지 설계/케이스 자체에 문제가 있는지. 후자의 경우 수정/롤백 메커니즘을 거칩니다). 모든 단계가 완료되면 회귀 테스트 케이스(T-R) 세트를 한 번 실행합니다.
• 설계 문서와 일치하지 않는 상황이 발생하면 멈춥니다: 먼저 02-설계.md를 업데이트하고(변경 기록 포함), 그 다음 03-구현.md와 04-테스트.md를 동기화하여 수정한 후(케이스는 설계 변경에 따라 변경), 계속 진행합니다. 절대 설계에서 벗어나면서 하지 마십시오.
• 구현 과정에서 발견된 설계 결함, 새로운 제약 사항, API 변경 사항은 모두 02-설계.md의 '설계 변경 기록' 블록에 다시 작성하여 설계 문서를 최신 상태로 유지합니다.
• 각 단계 전환, 각 중요 시점마다 00-태스크-상태.md와 docs/design/README.md를 업데이트합니다.

구현 단계의 변경: 수정 메커니즘 vs 롤백 메커니즘

워크플로우는 명목상 논의→설계→구현 계획→구현이지만, 구현 중에 설계와 요구 사항/현실 간의 차이가 발견되는 것은 예상된 정상적인 현상이지, 예외가 아닙니다 — 아무리 완벽한 설계라도 구현 세부 사항을 100% 예측할 수는 없습니다.

차이는 두 가지 유형으로, 성격이 완전히 다르므로 엄격히 구분하여 각각의 프로세스로 처리해야 합니다:

	수정	롤백
본질	설계는 대체로 맞지만, 추가/보완이 필요한 결함/누락이 있음	이 부분 설계가 근본적으로 틀려서 완전히 다시 해야 함
주요 설계	변경하지 않음	폐기
완료된 산출물	폐기하지 않음	일부 폐기
빈도	정상적	드묾
일반적인 시나리오	누락된 필드, 브랜치, 사전 값, 고려하지 못한 새로운 요구 사항	방향 오류, 핵심 가정이 성립하지 않음, 실제 비즈니스와 맞지 않음

먼저 어느 유형에 속하는지 판단 (판단 책임은 각 메커니즘 설명 참조)하고, 해당 프로세스에 따라 처리합니다. 판단이 애매할 때는 먼저 '수정'으로 처리하고 사용자와 확인하는 쪽으로 기울입니다. 명확하게 근본적인 오류인 경우에만 '롤백'을 진행합니다.

수정 메커니즘 (정상적, 가벼움, 증분)

판단 세 가지 조건 (모두 충족해야 수정) :

• 주요 설계 방향에 문제가 없음
• 완료된 산출물을 폐기할 필요가 없음
• 단지 보충/미세 조정 (필드 보충, 브랜치 보충, 사전 값 보충, 누락된 새로운 요구 사항 포인트 보충 등)

처리 프로세스 (엄격한 순서, 순서를 바꿀 수 없음) :

1. 현재 구현 중단
2. 먼저 설계 문서 업데이트: 설계 문서의 해당 블록에 내용을 보충하고, 설계 변경 기록 한 줄 추가
3. 사용자가 이 수정을 확인할 때까지 대기 (스스로 결정하고 구현할 수 없음)
4. 사용자 확인 후, 구현 문서 동기 수정
5. 그런 다음 구현 계속

핵심 원칙: 먼저 설계 업데이트, 그 다음 구현. 순서는 바꿀 수 없음 — '구현을 먼저 완료하고 나중에 설계 문서에 기록하는 것'은 금지됩니다. 이는 설계 문서를 사후 기록이 아닌 사실 출처로 퇴보시킵니다. 단지 필드 하나를 추가하는 경우라도 이 프로세스를 완전히 거쳐야 합니다.

롤백 메커니즘 (드묾, 무거움, 폐기)

판단 세 가지 조건 (모두 충족해야 롤백) :

• 주요 설계 방향에 문제가 있음
• 완료된 산출물을 폐기해야 함
• 재논의/재설계 필요

판단 책임: 롤백의 최종 결정권은 사용자에게 있습니다. AI가 근본적인 문제로 의심되는 것을 발견하면, 제안만 할 수 있으며 롤백 의심 사유를 설명하고 사용자가 최종적으로 롤백 여부를 판단합니다. AI는 스스로 롤백을 판단할 수 없습니다.

처리 프로세스:

1. 현재 구현 중단
2. AI가 롤백 의심을 제안하고, 사유 설명 (어느 부분의 방향이 잘못되었는지, 왜 성립하지 않는지)
3. 사용자가 최종 판단할 때까지 대기 (롤백 여부)
4. 사용자가 롤백을 확인하면, 00-태스크-상태.md에 한 줄 기록: X 단계에서 Y 단계로 롤백, 이유, 폐기된 산출물
5. 논의/설계 단계로 돌아가 다시 정렬
6. 생성된 새 설계는 원래 프로세스에 따라 축적: 새로운 질문은 01-커뮤니케이션-과정.md의 미결 질문 목록으로; 설계 변경은 02-설계.md로 변경 기록 추가
7. 03-구현.md 동기 수정

두 메커니즘의 공통 철칙

1. 설계 변경은 항상 설계 문서를 수정하고, 구현 문서를 직접 수정하지 않음
2. 먼저 설계 업데이트, 그 다음 구현. 순서는 바꿀 수 없음 (나중에 하는 것 금지)
3. 모든 변경은 태스크 상태 문서에 흔적을 남겨야 함 (수정은 설계 변경 기록, 롤백은 추가 롤백 기록)
4. 사용자 확인은 모든 변경의 필수 게이트 (수정은 설계 보충 확인 필요; 롤백은 판단 자체 확인 필요)

마음가짐: 차이는 두렵지 않습니다. 차이를 무시하고 억지로 진행하거나 조용히 설계에서 벗어나는 것이 두렵습니다. '수정'을 가볍고 마찰이 적게 만들고 (정상적인 경우 원활해야 함), '롤백'을 신중하게 만듭니다 (폐기 및 재시작은 사용자가 결정). 둘 다 규범적으로 기록하여 재작업 비용을 최소화합니다.

구현 문서의 단계 표시 규칙

구현 단계는 대단계와 소단계의 두 계층으로 나뉘며, 각각 독립적인 완료 표시가 있어야 합니다. 대단계는 제목으로 블록을 나누고 진행 상황 카운트를 포함하며, 소단계는 4상태 체크박스를 사용합니다.

4상태 표시:

- [ ]  시작 전
- [~] 진행 중
- [x] 완료
- [!] 차단 (뒤에 이유 명시)

구성 예시:

### 1. 데이터베이스 계층 ✅ 1/3
- [x] 1.1 users 테이블 생성 (마이그레이션 스크립트 포함)
- [~] 1.2 인덱스 생성
- [ ] 1.3 시드 데이터 작성

### 2. 인터페이스 계층 ⬜ 0/2
- [ ] 2.1 POST /api/users 구현
- [ ] 2.2 인증 미들웨어 연결

대단계 상태 기호:

• ⬜ 시작 전 (0/N 완료)
• 🌗 진행 중 (일부 완료)
• ✅ 모두 완료 (N/N)

진행 상황 카운트 형식은 통일하여 완료된 수/총 수로 대단계 제목 끝에 배치합니다. 이렇게 하면 전체 진행 상황을 볼 수 있을 뿐만 아니라 정확히 어떤 소단계에서 막혔는지도 파악할 수 있습니다.

백엔드 프로젝트의 특별 처리

현재 프로젝트가 순수 백엔드 프로젝트인 경우 (프론트엔드 코드가 없거나, 프론트엔드와 백엔드가 분리되어 백엔드가 독립적인 리포지토리인 경우):

• 설계 문서와 구현 문서는 백엔드 내용만 작성하며, 프론트엔드 구현은 포함하지 않습니다.
• 새로운 인터페이스 또는 기존 인터페이스 변경 (URL, 메서드, 입력, 출력, 오류 코드, 인증 요구 사항 등)은 반드시 02-설계.md에 전용 '인터페이스 변경 목록' 블록을 설정하여 집중적으로 표시해야 합니다.
• 인터페이스 목록 형식은 프론트엔드 개발자가 직접 가져가서 연동할 수 있도록 해야 합니다. 권장 필드: 인터페이스 경로, 요청 메서드, 요청 본문 예시, 성공 응답 예시, 오류 코드 표, 인증 요구 사항, 비고.
• 이 인터페이스 목록은 프론트엔드에 전달하는 산출물이므로, 자체적으로 완결되고 독립적으로 읽을 수 있어야 합니다.
• 인터페이스 목록은 설계 단계에서 확정적인 결론을 내야 하며, 판단을 구현 단계로 미루는 것을 금지합니다. '이 인터페이스는 신규인가 변경인가', '경로는 기존 것을 사용하는가 변경하는가', '입력 필드는 어떤 기존 구조에 맞출 것인가' 등 기존 코드에 의존해야만 결정할 수 있는 사실은 반드시 설계 단계에서 기존 코드를 읽어 확인하고, 결론을 인터페이스 목록에 작성해야 합니다. '설계 단계에서는 논의만 하고 코드를 작성하지 않는다'는 제약은 비즈니스 코드에 적용됩니다. 인터페이스 형태를 확인하기 위해 기존 코드를 읽는 것은 설계 조사에 속하며, 구현이 아니므로 제약을 위반하지 않습니다. 설계 문서에는 '구체적으로는 기존 코드에 따라 다름', '구현 단계에서 확인'과 같은 모호한 표현을 금지하며, '[구현 단계 확인]'과 같은 태그로 불확실성을 합법화하는 것도 허용하지 않습니다. 인터페이스 목록을 프론트엔드에 전달할 때는 완전히 확정되어야 합니다. 그렇지 않으면 프론트엔드가 연동할 수 없습니다.

수락 기준과 테스트 (세 계층 책임)

테스트는 구현 단계에서 임시로 보충하는 것이 아니라, 설계부터 구현까지贯穿하는 체계입니다. 세 계층의 책임은 엄격히 분리됩니다:

계층	매체	내용	성격	산출 단계
규칙	02-설계.md	추상적 수락 기준	'어느 정도까지 해야 요구 사항을 충족하는지'	설계
인스턴스	04-테스트.md	구체적인 테스트 케이스	'무슨 입력을 넣고, 무슨 출력을 예상하는지'	구현 계획
동작	03-구현.md	단계 + 케이스 참조	'무슨 동작을 하고, 어떤 케이스와 대조하여 검증할지'	구현 계획

왜 이렇게 나누는가: 수락 기준은 요구 사항 경계 (설계에 속함), 케이스는 경계의 인스턴스화, 구현은 실행 동작입니다. 세 계층을 분리하면, 규칙이 바뀌면 설계 문서에서 찾고, 케이스가 바뀌면 테스트 문서에서 찾고, 동작이 바뀌면 구현 문서에서 찾을 수 있습니다 — 각각 사실 출처가 있어 서로 오염되지 않습니다.

테스트 케이스 계층과 번호:

접두사	유형	용도
T-F-	기능 케이스	정상 흐름
T-EX-	예외 케이스	역방향, 경계, 오류 브랜치
T-R-	회귀 케이스	수정/롤백 후 반드시 테스트해야 하는 중요 경로 (F/EX에서 선별, A 수정 시 B 손상 방지)
T-API-	인터페이스 케이스	설계 문서 '인터페이스 변경 목록'의 각 인터페이스에 해당

모든 태스크는 강제로 04-테스트.md를 생성합니다: 이 스킬은 중대형 태스크를 대상으로 하며, 작은 요구 사항은 사용자가 이 스킬을 트리거하지 않습니다. 따라서 복잡도 판단을 하지 않습니다 — 태스크가 일단 구현 계획 단계에 진입하면 테스트 문서는 필수 산출물입니다.

수정/롤백과 테스트의 관계: 수정 또는 롤백 메커니즘을 거친 후, 설계가 변경되었습니다 → 케이스도 함께 업데이트 (먼저 설계 수락 기준 수정, 그 다음 테스트 케이스 수정), 그리고 회귀 테스트 케이스 세트(T-R)를 최소한 한 번 다시 실행하여 국소적 수정이 전체 회귀를 유발하지 않도록 방지합니다.

확장 모드 A: 태스크 분할 (대규모 다중 모듈 태스크)

언제 활성화: 대규모 태스크가 자연스럽게 여러 반독립적인 모듈을 포함하는 경우 (예: '검토 시스템 = 민감어 필터링 + 이미지 검토 + 수동 검토 워크벤치'), 단일 컨텍스트로는 감당하기 어렵습니다. 사용자가 논의 단계에서 명시적으로 '대규모 태스크이므로 여러 모듈로 분할합니다'라고 말할 때 활성화합니다. 태스크 규모를 자동으로 판단하지 않으며, 반드시 사용자가 명시적으로 트리거해야 합니다.

핵심 메커니즘: 부모 태스크는 전체 설계 + 모듈 분할 + 모듈 간 인터페이스 계약 + 오케스트레이션을 담당하고, 자식 태스크는 부모 태스크의 경계 내에서 각각 완전한 4단계 프로세스를 따릅니다.

A.1 부모-자식 태스크의 문서 구조 (중첩형)

프로젝트 루트/docs/design/
├── README.md                          ← 전역 태스크 개요
├── 01-검토-시스템/                     ← 부모 태스크
│   ├── 00-태스크-상태.md                 ← parent-task-status.md 템플릿 사용, 자식 태스크 목록 포함
│   ├── 01-커뮤니케이션-과정.md                 ← 부모 태스크 수준의 전체 논의
│   ├── 02-설계.md                     ← 전체 아키텍처 + 모듈 분할 + 모듈 간 인터페이스 계약
│   ├── 03-구현.md                     ← 부모 수준 오케스트레이션만 (통합 테스트, 연동), 모듈 내부는 작성하지 않음
│   ├── 04-테스트.md                     ← 모듈 간 통합 테스트만
│   └── 자식-태스크/
│       ├── 01-1-민감어-필터링/           ← 자식 태스크 (완전한 4단계 문서, 일반 템플릿 사용)
│       ├── 01-2-이미지-검토/
│       └── 01-3-수동-검토-워크벤치/
└── 02-기타-태스크/

자식 태스크는 일반 템플릿 (task-status / communication / design / implementation / test)을 사용하며, 전혀 변경되지 않습니다. 부모 태스크는 assets/parent-task-status.md 템플릿을 사용하며, '자식 태스크 목록' 블록이 추가됩니다. 부모 태스크의 설계 문서는 일반 설계 템플릿을 기반으로 추가로 두 개의 블록을 반드시 포함해야 합니다:

• 모듈 분할: 어떤 자식 태스크로 분할되는지, 각각의 책임 경계 나열
• 모듈 간 인터페이스 계약: 자식 태스크 간의 인터페이스 규약 (인터페이스 시그니처, 데이터 형식, 호출 방식 등). 이는 자식 태스크가 독립적으로 병렬 실행될 수 있게 하는 핵심이며, 설계 단계에서 반드시 명확히 정의해야 합니다.

A.2 부모 태스크의 단계 진행 (엄격한 직렬)

1. 부모 태스크가 먼저 '논의 + 설계'를 진행하며, 반드시 모듈 분할 + 모듈 간 인터페이스 계약을 산출해야 합니다.
2. 부모 태스크 설계가 사용자 확인을 거친 후에만 자식 태스크를 시작할 수 있습니다.
3. 자식 태스크를 시작할 때 의존 관계에 따라 시작 순서를 정합니다: 부모 태스크 설계 단계에서 자식 태스크 간의 의존 관계를 명확히 해야 합니다 (예: '수동 검토 워크벤치는 민감어 필터링의 인터페이스에 의존'). 의존되는 자식 태스크가 먼저 완료되어야 의존하는 쪽이 시작할 수 있습니다.
4. 각 자식 태스크는 완전한 4단계 프로세스를 따릅니다 (의존 관계가 충족된다는 전제 하에 병렬 가능). 여러 자식 태스크를 병렬로 시작하는 방법은 사용하는 에이전트 프레임워크에 따라 결정됩니다 (일반적으로 백그라운드/비동기 자식 태스크 기능을 통해 구현). 구체적인 구현 참고는 B.5를 참조하십시오.
5. 모든 자식 태스크가 완료되면, 부모 태스크가 '모듈 간 통합 테스트'로 마무리합니다.

왜 부모 태스크와 자식 태스크를 병렬로 실행할 수 없는가: 부모 태스크의 핵심 산출물은 모듈 간 인터페이스 계약이며, 이는 자식 태스크가 독립적으로 실행될 수 있는 전제 조건입니다. 부모 태스크 설계가 확정되지 않은 상태에서 자식 태스크를 시작하면 자식 태스크 간에 반드시 충돌이 발생합니다.

A.3 자식 태스크는 부모 태스크가 정의한 인터페이스 계약을 임의로 변경할 수 없습니다.

인터페이스 계약은 다중 모듈의 합의이며, 어느 한 자식 태스크가 임의로 변경하면 다른 자식 태스크가 통제 불능 상태가 됩니다. 자식 태스크가 부모 태스크의 인터페이스 계약에 문제를 발견한 경우:

• 스스로 인터페이스 계약을 수정할 수 없음
• 반드시 부모 태스크로 돌아가 수정 메커니즘을 따라야 함: 부모 태스크의 02-설계.md 업데이트 (변경 기록 포함) → 사용자 확인 대기 → 해당 인터페이스에 의존하는 모든 자식 태스크에 통지 → 영향을 받은 자식 태스크가 자신의 설계/구현/테스트를 동기 수정

A.4 중첩 깊이 제한: 한 단계만 허용

부모→자식, 더 이상 중첩할 수 없음 (자식 태스크는 자신의 자식 태스크를 가질 수 없음). 이유: 중첩 단계가 너무 많으면 태스크 관계가 매우 복잡해집니다. 자식 태스크를 다시 분할해야 한다면, 일반적으로 태스크 분할 단위가 잘못된 것입니다 — 해당 태스크 자체가 독립적인 부모 태스크로 재계획되어야 하며, 기존의 다중 계층 구조에 억지로 넣어서는 안 됩니다.

A.5 부모 태스크 템플릿 사용

• 부모 태스크 상태 문서: assets/parent-task-status.md 사용 (일반 task-status 템플릿 사용 금지)
• 부모 태스크의 다른 문서 (커뮤니케이션 과정/설계/구현/테스트): 일반 템플릿 사용하지만, 설계 문서는 반드시 A.1에서 설명한 두 개의 블록을 추가로 포함해야 함
• 자식 태스크의 모든 문서: 일반 템플릿 사용, 전혀 변경 없음

확장 모드 B: 이중 에이전트 구현 (구현 분할)

언제 활성화: 단일 태스크 내에서 구현+테스트 두 단계가 쌓여 컨텍스트가 너무 길어질 때. 사용자가 구현 단계 시작 시 명시적으로 '구현은 이중 에이전트 모드를 사용'이라고 말할 때 활성화합니다. 자동으로 판단하지 않으며, 반드시 사용자가 명시적으로 트리거해야 합니다.

핵심 메커니즘: 구현 단계를 두 개의 직렬 단계로 분할합니다 — 구현 에이전트 (03-구현.md에 따라 코드 작성) + 테스트 에이전트 (04-테스트.md에 따라 검증). 두 에이전트는 물리적으로 독립적인 두 개의 에이전트 (두 개의 독립적인 컨텍스트)이며, 태스크 상태 문서를 통해 인계합니다. B의 핵심 가치는 컨텍스트 격리입니다: 구현 에이전트는 테스트 컨텍스트를 가지지 않고, 테스트 에이전트는 구현 세부 사항을 가지지 않습니다.

B.1 구현과 테스트의 책임 경계

• 구현 에이전트: 03-구현.md의 단계만 수행 (코드 작성), 완료 후 스스로 테스트를 실행하지 않고, 00-태스크-상태.md의 '구현 분할 상태' 블록에 '구현 완료, 버전 X, 테스트 단계 진입 가능'을 선언합니다.
• 테스트 에이전트: 최신 03-구현.md + 04-테스트.md를 기반으로 검증합니다. 책임은 엄격히 '테스트 케이스 실행, 실패 판단, 보고'로 제한되며, 코드 수정을 담당하지 않습니다 (구현 버그를 발견해도 스스로 수정하지 않음).

B.2 테스트 에이전트가 실패를 발견했을 때의 처리

테스트 에이전트가 테스트 케이스 실행에 실패하면, 실패 근본 원인을 1차 판단합니다 (테스트 에이전트는 실제 동작을 보기 때문에 1차 판단에 가장 유리한 정보를 가집니다):

• 구현 버그로 판단 (코드가 잘못 작성되었고, 설계는 올바름) → 구현 에이전트에 보고, 구현 에이전트가 수정. 수정 후 반드시 테스트 에이전트로 돌아가 해당 케이스를 재테스트해야 하며, 통과해야 다음 단계로 진행할 수 있습니다 (구현 에이전트가 일방적으로 '수정 완료'를 선언하는 것으로 종결할 수 없음).
• 설계 버그로 판단 (코드는 설계대로 작성되었지만, 설계 자체에 문제가 있음) → 스스로 설계를 수정할 수 없으며, 수정 메커니즘을 트리거합니다: 중단 → 설계 업데이트 → 사용자 확인 대기 → 구현 수정 → 테스트 수정 → 테스트 에이전트로 돌아가 재테스트

판단이 잘못되면 사용자가 바로잡습니다. 그러나 '설계 수정'은 영향 범위가 크므로 반드시 사용자가 결정해야 합니다.

B.3 구현 분할 상태 블록

00-태스크-상태.md에 선택적 블록을 추가합니다 (B 모드 활성화 시에만 채우고, 일반 모드에서는 채우지 않음):

## 구현 분할 상태 (B 모드 전용, 일반 모드는 비워둠)

- 현재 단계: 구현 / 테스트
- 구현 버전: (구현 에이전트가 완료 또는 수정할 때마다 증가)
- 구현 완료 선언: YYYY-MM-DD, 구현 에이전트가 테스트 진입 가능을 선언함
- 테스트 진행 상황:
  - 통과: T-F-01, T-F-02, ...
  - 실패 수정 대기: T-EX-03 (구현 버그, 구현 에이전트에 보고됨), ...
  - 재테스트 대기: T-EX-03 (구현 에이전트가 수정 완료, 테스트 에이전트 재테스트 대기)

구현 에이전트와 테스트 에이전트 모두 이 블록을 읽고 쓰며, 이것이 둘 사이의 유일한 인계 지점입니다.

B.4 A와의 조합 (A+B)

A와 B는 직교하므로 조합 가능합니다: 대규모 태스크는 A에 따라 자식 태스크로 분할되고, 각 자식 태스크 내부는 B에 따라 구현+테스트로 분할됩니다. 조합 시 추가 메커니즘이 필요하지 않습니다 — 자식 태스크는 일반 태스크이기 때문입니다 (A.1에서 자식 태스크는 일반 템플릿을 사용한다고 설명했습니다). 따라서 자식 태스크 내부는 자연스럽게 B를 지원합니다. 활성화 방식: 부모 태스크 설계 + 자식 태스크 시작 후, 각 자식 태스크는 구현 단계가 시작될 때 B를 활성화할지 결정합니다.

B.5 에이전트 스케줄링 안내

B 모드는 두 개의 물리적으로 독립적인 에이전트 (구현 에이전트와 테스트 에이전트)를 필요로 하며, 이들은 '구현 분할 상태' 블록을 통해 간접적으로 인계하고, 서로 직접 통신하지 않습니다. 두 에이전트를 어떻게 교대하게 할지는 사용하는 에이전트 프레임워크에 따라 다릅니다.

어떤 프레임워크를 사용하든, 동일한 일반 스케줄링 패턴을 따릅니다:

1. 스케줄러(주 에이전트, 외부 오케스트레이션 스크립트 또는 사용자本人일 수 있음)가 '구현 분할 상태' 블록을 읽고 현재 단계를 판단합니다.
2. 스케줄러가 구현 에이전트를 시작하고, 설계/구현 문서 경로를 전달하며, 03-구현.md에 따라 진행하고 완료 후 상태 블록을 업데이트하도록 지시합니다.
3. 구현 단계가 끝나면, 스케줄러가 테스트 에이전트를 시작하고, 테스트 문서 경로를 전달하며, 04-테스트.md에 따라 테스트 케이스를 실행하고 결과 (실패 판단 포함)를 상태 블록에 기록하도록 지시합니다.
4. 스케줄러는 상태 블록의 테스트 결과에 따라 다음 단계를 결정합니다: 구현 버그이면 구현 에이전트로 돌아가 수정 및 재테스트; 설계 버그이면 중단하고 사용자에게 수정 메커니즘을 보고; 모두 통과하면 마무리.

일반적인 핵심 사항:

• 구현 에이전트와 테스트 에이전트는 각자 독립적으로 컨텍스트를 구축하며, 서로 오염되지 않습니다 — 이것이 B 모드 '컨텍스트 격리'의 핵심입니다.
• 두 에이전트는 서로를 직접 인식하지 않고, '구현 분할 상태' 블록이라는 공유 문서를 통해서만 간접적으로 인계합니다.
• 스케줄러는 '상태 읽기 → 판단 → 전달'만 수행하며, 구현이나 테스트 자체에는 참여하지 않습니다.

특정 클라이언트의 구현 참고: 각 에이전트 프레임워크의 하위 에이전트 / 백그라운드 태스크 / 다중 창 기능은 서로 다릅니다. 이 문서는 특정 구현에 국한되지 않습니다. ZCode를 사용하는 경우 assets/references/zcode-scheduling.md를 참조하십시오 (필요 시 로드: B 모드 활성화 및 구체적인 작업 지침이 필요할 때만 읽음). 다른 클라이언트는 이 파일의 아이디어를 참조하여 자신의 능력에 맞게 조정할 수 있습니다.

중요한 경계: 스킬은 구체적인 스케줄링 구현에 국한되지 않음

스킬이 정의하는 것은 인계 프로토콜(구현 분할 상태 블록의 형식과 의미)과 역할 책임(구현/테스트가 각각 무엇을 하는지)이며, 구체적인 스케줄링 방법에 국한되지 않습니다. '파일 읽기, 하위 태스크 시작, 파일 쓰기'가 가능한 모든 프레임워크가 B 모드를 구현할 수 있습니다.

단계 전환의 확인 원칙

단계 간은 자동으로 전환되지 않으며, 명시적인 신호가 필요합니다:

진입 조건	충족 조건
논의 진입	(스킬이 수동으로 활성화되면 시작)
논의 → 설계	사용자가 명시적으로 설계 확정에 동의하고, 미결 질문 목록이 비어 있어야 함
설계 → 구현 계획	설계 문서가 완료되고 사용자의 승인을 받아야 함
구현 계획 → 구현	사용자가 명시적으로 구현 시작을 요청해야 함
구현 → 설계 (수정)	구현 중 설계 결함 발견 시, '수정 메커니즘'에 따라 중단 후 설계 수정, 사용자 확인 대기
구현 → 논의/설계 (롤백)	구현 중 근본적인 오류 발견 시, AI가 롤백 제안, 사용자가 최종 판단 후 롤백

전환 여부가 확실하지 않으면, 기본적으로 현재 단계에 머물러 논의를 계속하고, 사용자에게 적극적으로 질문합니다. 사용자를 대신하여 '설계가 이미 충분히 좋으니, 작성을 시작해도 된다'는 판단을 내리지 마십시오.

템플릿 사용

새 문서를 만들 때는 assets/ 디렉토리에서 해당 템플릿을 읽습니다:

• assets/readme.md → docs/design/README.md (전역 태스크 개요)
• assets/task-status.md → 00-태스크-상태.md (일반 태스크 / 자식 태스크)
• assets/parent-task-status.md → 00-태스크-상태.md (부모 태스크 전용, A 모드 활성화 시)
• assets/communication.md → 01-커뮤니케이션-과정.md
• assets/design.md → 02-설계.md (수락 기준 블록 포함; 부모 태스크는 추가로 모듈 분할 + 인터페이스 계약 블록 포함 필요)
• assets/implementation.md → 03-구현.md
• assets/test.md → 04-테스트.md (구현 계획 단계에서 생성)

템플릿을 읽고, 실제 내용을 채우고, 태스크 폴더에 작성합니다. 문서 구조를凭空으로 만들어 내지 마십시오.

스킬 반복과 기존 태스크 문서

스킬은 지속적으로 반복되며, 템플릿과 규칙이 업데이트될 수 있습니다. 하지만 이미 사용 중인 기존 태스크 문서는 새 규칙으로 자동 마이그레이션되지 않습니다. 이는 의도적인 것입니다 — 목적은 사용자의 문서 구조에 대한 기존 기억을 보호하고, 다중 컨텍스트 메모리 메커니즘의 안정성을 유지하는 것입니다. 문서 구조는 사용자가 컨텍스트를 전환한 후 빠르게 위치를 찾을 수 있는 메모리 앵커이며, 앵커는 스킬 업그레이드로 인해 빈번하게 변형되어서는 안 됩니다.

처리 원칙:

• 능동적으로 마이그레이션하지 않음: AI는 기존 태스크를 임의로 스캔하거나 규칙을 임의로 정렬하지 않습니다. 기존 문서 형식이 새 규칙과 차이가 있더라도 (예: 기존 문서에 '롤백 기록' 블록이 있고 새 규칙이 '변경 기록'을 요구하는 경우). 차이점이 발견되면 '구현 단계 메모'나 대화 중에 한마디 언급할 수는 있지만, 임의로 손대지 않습니다.
• 사용자의 명시적인 지시가 있을 때만 마이그레이션: 사용자가 '태스크 X의 문서를 현재 스킬 규칙에 맞춰 정렬', '태스크 X를 새 형식으로 마이그레이션' 등과 같이 능동적으로 요청할 때만 수행합니다. AI는 사용자를 대신하여 '이 기존 태스크를 마이그레이션해야 하는지' 판단하지 않습니다.
• 증분 보충 우선: 마이그레이션은 기본적으로 새 규칙과 일치하지 않는 부분만 보충/수정하며, 원본 문서의 전체 구조와 내용을 유지하고, 완전히 다시 작성하지 않습니다. 이렇게 하면 사용자가 컨텍스트를 전환하여 돌아왔을 때 문서 전체를 다시 읽고 이해할 필요가 없습니다 — 구조가 변경되지 않았고, 메모리 앵커가 그대로 있습니다.
• 사용자가 명시적으로 재작성을 요청하는 경우, 재작성을 지원하지만 반드시 먼저 원본 파일을 백업한 후 새 파일을 생성해야 합니다:
  • 원본 파일에 직접 덮어쓰지 않음
  • 백업 파일에 날짜 또는 버전 접미사를 추가합니다 (예: 00-태스크-상태.md.bak.20260617)
  • 새 파일은 원본 파일 이름을 사용하여 재작성된 내용을 담습니다.
  • 원본 파일은 사용자의 과거 메모리 앵커이므로, 재작성하더라도 원본 버전을 보존하여 비교 또는 롤백에 대비해야 합니다.
• 마이그레이션/재작성 전에 먼저 범위를 설명: 작업을 시작하기 전에 사용자에게 어떤 부분을 변경할지 (증분) 또는 어떤 파일을 재작성할지 (전체) 알려주고, 완료 후 변경 사항을 간략히 설명하여 예측 가능성을 유지합니다.

안티 패턴 (피해야 할 것)

• ❌ 논의 단계에서 비즈니스 코드를 작성하기 시작 — 본말이 전도됨.
• ❌ 설계 변경을 구현 문서에 직접 작성하고 설계 문서를 업데이트하지 않음 — 단일 사실 출처를 파괴함.
• ❌ 새 대화에 진입했을 때 상태 문서와 README를 읽지 않고 사용자에게 진행 상황을 다시 설명하게 함 — 컨텍스트 낭비.
• ❌ 구현 중 차이가 발생했을 때 조용히 구현을 수정하고 설계 문서에 반영하지 않음 — 설계 문서가 점점 왜곡됨.
• ❌ 백엔드 프로젝트에서 프론트엔드 구현 세부 사항을 작성하거나, 인터페이스 변경이 인터페이스 목록에 반영되지 않음 — 프론트엔드가 연동 근거를 얻지 못함.
• ❌ 명시적인 신호 없이 자동으로 단계를 진행 — 사용자의 의사 결정권을 박탈.
• ❌ 구현 중 설계 결함 (누락된 필드/브랜치/사전 값 등) 발견 시 구현 문서를 직접 수정하고, 설계 문서에 반영하지 않으며, 사용자 확인을 기다리지 않음 — '수정 메커니즘'을 따라야 함: 중단 → 먼저 설계 수정 → 확인 대기 → 구현 수정 → 계속.
• ❌ 구현 중 근본적인 오류 발견 시 억지로 구현 문서를 수정하거나, AI가 스스로 롤백을 판단 — '롤백 메커니즘'을 따라야 함: AI는 제안만 가능, 사용자가 최종 판단, 롤백 기록 후 논의/설계 단계로 돌아가 다시 정렬.
• ❌ 대단계가 체크되었지만 내부 소단계가 아직 빠져 있음 — 대단계와 소단계 모두 독립적으로 표시해야 함.
• ❌ 논의가 분산되어 수렴되지 않고, 미결 질문이 새 주제에 묻힘 — 미결 질문 목록으로 강제 수렴.
• ❌ 인터페이스 목록에 '구체적으로는 기존 코드에 따라 다름', '구현 단계에서 확인'과 같은 모호한 표현이 나타나거나, [구현 단계 확인] 태그로 불확실성을 합법화 — 기존 코드에 의존하는 사실은 설계 단계에서 코드를 읽어 확인해야 하며, 설계 문서 전달 시 인터페이스 목록은 완전히 확정되어야 함. 그렇지 않으면 프론트엔드가 연동할 수 없음.
• ❌ 스킬 반복 후 기존 태스크 문서를 임의로 마이그레이션하거나 새 규칙에 임의로 정렬 — 사용자의 메모리 앵커를 파괴함. 사용자의 명시적인 지시가 있을 때만 마이그레이션; 기본적으로 증분 보충, 전체 재작성 금지; 사용자가 재작성을 요청하는 경우 반드시 먼저 원본 파일을 백업한 후 새 파일을 생성해야 함.
• ❌ 설계 문서에 설계만 작성하고 수락 기준을 작성하지 않음 — 수락 기준은 요구 사항 경계이며, 이것이 없으면 '완료'에 대한 객관적인 정의가 없어 구현 단계 검증이 감에 의존하게 됨.
• ❌ 구현 문서에 '단위 테스트로 XXX를 커버'와 같은 막연한 동작을 작성하고 구체적인 테스트 케이스 번호를 참조하지 않음 — 테스트 동작은 반드시 04-테스트.md의 구체적인 케이스를 가리켜야 함 (예: 'T-EX-03 대조 검증'). 그렇지 않으면 무엇을 테스트하고 예상 결과가 무엇인지 명확하지 않음.
• ❌ 수정/롤백 메커니즘을 거친 후 회귀 테스트 케이스(T-R)를 다시 실행하지 않음 — 국소적 변경이 전체 회귀를 유발할 수 있으므로 중요 경로를 반드시 재테스트해야 함.
• ❌ A 모드에서 부모 태스크 설계가 확정되지 않았는데 (모듈 분할 또는 인터페이스 계약이 산출되지 않음) 자식 태스크를 시작 — 자식 태스크 간에 반드시 충돌이 발생함. 부모 태스크의 설계는 먼저 사용자 확인을 거쳐야 함.
• ❌ A 모드에서 자식 태스크가 부모 태스크가 정의한 인터페이스 계약을 임의로 수정 — 인터페이스 계약은 다중 모듈의 합의이므로, 반드시 부모 태스크로 돌아가 수정 메커니즘을 거쳐야 하며, 해당 인터페이스에 의존하는 모든 자식 태스크에 통지해야 함.
• ❌ A 모드에서 자식 태스크가 다시 자식 태스크를 중첩 (한 단계 초과) — 일반적으로 분할 단위가 잘못되었음을 의미하며, 해당 자식 태스크는 독립적인 부모 태스크로 재계획되어야 함.
• ❌ A 모드에서 부모 태스크가 자식 태스크 간의 의존 관계를 정하지 않고 모든 자식 태스크를 병렬로 실행 — 의존하는 쪽이 의존되는 쪽이 완료되지 않아 중단됨. 의존 관계는 부모 태스크 설계 단계에서 반드시 명확히 해야 함.
• ❌ B 모드에서 테스트 에이전트가 직접 구현 버그를 수정 — 책임이 분리되어야 함: 테스트는 문제만 찾고, 수정은 구현 에이전트에 반환; 수정 후에는 반드시 테스트 에이전트가 재테스트해야 하며, 구현 에이전트가 일방적으로 종결을 선언할 수 없음.
• ❌ B 모드에서 동일한 에이전트를 직렬로 '구현'과 '테스트' 두 역할로 사용 — B의 핵심 가치는 컨텍스트 격리이며, 물리적으로 두 개의 독립적인 에이전트여야 함. 그렇지 않으면 컨텍스트가 전혀 격리되지 않아 B가 활성화되지 않은 것과 같음.
• ❌ B 모드에서 테스트 에이전트가 설계 버그를 발견하면 스스로 설계를 수정 — 설계 변경은 영향 범위가 크므로 반드시 수정 메커니즘을 트리거하고 사용자 확인을 거쳐야 함. 테스트 에이전트는 1차 판단하고 보고만 할 수 있음.