context

tddak:context

플러그인: tddak (TDD 강제 파이프라인) 이 스킬: context — Given-When-Then 강제 도메인 컨텍스트 관리 혼동 주의: ttutak:context와 거의 동일하나 AC 작성 시 Given-When-Then 시나리오 형식이 강제됨. 호출 시 주의: 이 스킬 내에서 다른 스킬을 호출할 때 반드시 tddak: 접두사를 사용한다.

도메인 컨텍스트를 관리한다. 상황에 따라 자동으로 적절한 모드를 선택한다.

Iron Law: Given-When-Then 강제

모든 수용 기준(AC)은 Given-When-Then 형식으로 작성한다. 자연어 서술 금지.

✅ 올바른 AC:
AC-1: 잘못된 비밀번호로 로그인 시도 시 에러 반환
  Given: 사용자가 등록되어 있고 비밀번호가 "correct"이다
  When: "wrong" 비밀번호로 로그인을 시도한다
  Then: 401 응답이 반환되고 "비밀번호 불일치" 메시지를 받는다

❌ 금지된 AC:
AC-1: 잘못된 비밀번호로 로그인하면 에러가 나와야 한다 (자연어 서술만)

판정 게이트: 작성된 AC가 "자동 테스트로 변환 가능한가?" 변환 불가 시 AC 재작성.

인자 파싱

Arguments 문자열에서 아래 규칙으로 파싱한다:

• --from <경로>: --from 다음 토큰을 파일 경로로 사용. 경로에 공백이 있으면 따옴표로 감싸진 것으로 간주.
• --sync: 진행도 동기화 모드. git 히스토리 기반으로 status.md 갱신.
• --from과 --sync를 제외한 나머지 토큰: 도메인명으로 사용.
• --sync와 --from은 동시 사용 불가. 동시 지정 시 "--sync와 --from은 동시에 사용할 수 없습니다." 안내 후 중단.
• 인자 없음: 도메인명과 --from, --sync 모두 없음.

예시:

• 결제 → 도메인명=결제, from=없음, sync=없음
• 정산 --from docs/req.md → 도메인명=정산, from=docs/req.md
• --from docs/req.md → 도메인명=없음, from=docs/req.md
• 결제 --sync → 도메인명=결제, sync=true
• (빈 인자) → 도메인명=없음, from=없음, sync=없음

수칙

• 모호하고 일반적인 표현을 허용하지 않는다. 답변이 "효율화", "개선" 같은 추상어로만 구성되면 구체화를 요청한다.
• 누락된 데이터를 가정하지 않는다. 사용자가 모르는 항목은 ❓로 남기되, 빈칸이 있다는 것을 명시한다.
• 정량화를 요구한다. "많이", "자주" 대신 숫자를 묻는다. 정확하지 않아도 추정치라도 기록한다.
• 충분한 정보가 모일 때까지 산출물로 넘어가지 않는다. 필수 질문 답변이 모두 모호하면 1라운드 더 진행한다.

모드 자동 판단

인자와 현재 상태를 기반으로 모드를 결정한다:

조건	모드	동작
context/ 폴더 없음 + 인자 없음	스캔	코드베이스 분석 → context 초안 자동 생성
context/ 폴더 없음 + 도메인명 지정	스캔+신규	코드베이스 스캔 후 해당 도메인 우선 생성
context/ 있음 + 도메인명 지정 + --from 없음	신규	Q&A 기반 새 도메인 생성
context/ 있음 + 도메인명 지정 + --from <파일>	문서 기반	파일 읽고 → 내용 기반으로 context 생성/갱신
context/ 있음 + --from <파일> + 도메인명 없음	문서 기반	파일에서 도메인명을 추론하여 생성/갱신
context/ 있음 + 인자 없음	선택	사용자에게 질문: 새 도메인 추가 / 기존 도메인 갱신 / 코드베이스 재스캔
context/{도메인}/ 이미 존재 + --from <파일>	갱신	파일 읽고 기존 context와 비교 → 변경 제안
context/{도메인}/ 이미 존재 + --from 없음	갱신	사용자에게 갱신 대상 확인 후 Q&A
context/{도메인}/ 존재 + --sync	동기화	git log/PR 분석 → status.md 갱신

---

모드 A: 스캔 (코드베이스 분석)

context/ 폴더가 없거나 사용자가 재스캔을 선택한 경우 실행한다.

A-0. 사용자 확인

AskUserQuestion: "context/ 디렉토리가 없습니다. 코드베이스를 분석하여 도메인 구조를 자동 생성할까요?"

• 예 → A-1로 진행
• 아니오 → 모드 B(신규)로 전환하여 수동 생성

A-1. 프로젝트 구조 스캔

아래 항목을 병렬로 탐색한다:

1. 패키지/디렉토리 구조: src/ 하위 최상위 2레벨을 스캔하여 도메인 분류를 추론한다.
   • Java: src/main/java/{base-package}/ 하위 패키지를 도메인 후보로 식별
   • Node: src/ 하위 디렉토리 구조를 분석 (modules/, features/, domains/ 등)
2. 엔티티/모델: *Entity.java, *.entity.ts, *Model.* 등 도메인 모델 파일을 탐색한다.
3. API 엔드포인트: *Controller.java, *Router.*, routes/ 등을 스캔한다.
4. 설정 파일: application.yml, application.properties, .env, package.json 등을 읽는다.
5. README/문서: 프로젝트 루트의 README.md, docs/ 디렉토리를 확인한다.

A-2. 도메인 분류

스캔 결과에서 도메인을 추론한다:

• 패키지 구조 기반: com.example.payment → 결제 도메인
• 엔티티 클러스터 기반: 관련 엔티티를 그룹핑
• API 엔드포인트 기반: /api/orders/** → 주문 도메인

A-3. 초안 생성

각 감지된 도메인에 대해:

1. 도메인별 디렉토리 생성: mkdir -p context/{도메인}/
2. context/ 루트 파일 초기화 (필요시):
   • test -f context/README.md 가 false인 경우, B-0과 동일하게 context/README.md 생성
   • test -f context/glossary.md 가 false인 경우, B-0과 동일하게 context/glossary.md 생성
3. 스캔 결과를 기반으로 각 문서 초안 작성:
   • README.md: 도메인 개요 (스캔에서 파악한 범위, 주요 기능)
   • PROJECTS.md: 현재 레포를 자동 등록 (git remote get-url origin)
   • glossary.md: 엔티티명, 주요 상수, enum 값 등에서 추출한 용어 초안
   • architecture.md: 패키지 구조, 레이어 구조 요약
   • status.md: 빈 템플릿

A-4. 사용자 검토

생성된 초안을 사용자에게 보여주고 확인을 받는다:

• "N개 도메인을 감지했습니다: {목록}. 확인해주세요."
• 사용자가 도메인을 추가/제거/이름 변경할 수 있다.
• 각 도메인의 README.md 초안을 보여주고 수정 사항을 반영한다.
• 담당자 정보를 질문한다: "각 도메인의 담당 PM/PO와 개발 리드를 알려주세요."

A-5. 확정 및 인덱스 생성

사용자 확인 후:

• 수정 사항을 반영하여 최종 문서를 Write한다.
• context/README.md 도메인 테이블을 업데이트한다.
• 완료 안내: 생성된 도메인 수, 파일 수, ❓ 항목 안내.

---

모드 B: 신규 (Q&A 기반)

Q&A 기반으로 새 도메인을 생성한다.

B-0. context/ 디렉토리 초기화

프로젝트 루트에 context/ 디렉토리가 없으면 자동 생성한다:

1. test -d context/ 로 존재 여부 확인
2. 존재하지 않으면:
   • mkdir -p context/
   • context/README.md 생성 (도메인 목록 인덱스 템플릿):

     # 프로젝트 컨텍스트
     
     도메인 지식, 아키텍처, 용어 사전을 정리하는 공간입니다.
     
     ## 도메인
     
     | 도메인 | 설명 | 상세 |
     |--------|------|------|
     
     ## 공통
     
     - [공통 용어 사전](glossary.md)
     

   • context/glossary.md 생성 (공통 용어 사전 스켈레톤):

     # 공통 용어 사전
     
     > 도메인을 가리지 않고 프로젝트 전체에서 쓰이는 용어입니다.
     > 도메인별 용어는 `context/{도메인}/glossary.md`를 참조하세요.
     
     | 용어 | 설명 |
     |------|------|
     

3. 이미 존재하면 건너뛴다.

B-1. 도메인 확인

• 인자로 도메인명이 주어지면 그대로 사용한다.
• 인자가 없으면 도메인명과 한 줄 설명을 묻는다.
• context/{도메인}/이 이미 존재하면 갱신 모드(D)로 전환할지 묻는다.

B-2. 검증 질문 (1라운드)

AskUserQuestion으로 아래 5개를 한 번에 묻는다:

1. 문제: 이 도메인에서 풀려는 문제가 뭔가?
2. 현재 프로세스: 지금은 어떻게 하고 있는가?
3. 안 하면: 이걸 안 하면 어떻게 되는가?
4. 사용자/규모: 예상 사용자와 규모는?
5. 담당: 이 도메인의 담당 PM/PO와 주요 개발자는?

B-3. 답변 품질 판단

답변을 받은 뒤 아래를 확인한다:

• 5개 중 3개 이상 구체적 → B-4단계로 진행
• 모호한 답변이 3개 이상 → 심화 질문 1라운드 추가 (B-3-1단계)

모호함 판단 기준:

• 정량 수치 없이 "많다", "자주", "크다"만 있는 경우
• 대상이 불명확한 경우 ("사용자들", "팀원들")
• "효율화", "개선", "자동화" 등 추상어만 있는 경우

B-3-1. 심화 질문 (선택적, 최대 1라운드)

모호했던 항목에 대해서만 구체화를 요청한다:

• 현재 프로세스 비용을 정량화할 수 있는가? (주당 시간, 빈도, 인력)
• 성공 기준을 숫자로 말할 수 있는가?
• 더 단순한 대안은 검토했는가?
• 실패 시 영향 범위는?

여전히 모르는 항목은 ❓로 남기고 진행한다. 2라운드 이상 반복하지 않는다.

B-4. 관련 프로젝트 확인

AskUserQuestion으로 묻는다:

• 관련 레포: 이 도메인과 관련된 GHE 레포가 있는가? (예: xx/factory-api, yy/factory-admin)

레포가 있으면 각 레포의 역할도 함께 기록한다. 아직 없으면 빈 테이블로 생성한다.

B-5. 디렉토리 및 문서 생성

mkdir -p context/{도메인}/ 로 도메인 디렉토리를 생성한다.

context/{도메인}/
├── README.md          ← 검증 질문 답변 정리
├── PROJECTS.md        ← 관련 프로젝트(레포) 목록
├── glossary.md        ← 용어 사전 스켈레톤
├── architecture.md    ← 전체 구조 요약 + 주제 문서 링크 (인덱스)
└── status.md          ← 구현 추적

B-6. README.md 작성

검증 질문 답변을 아래 구조로 정리한다:

# {도메인명}

{한 줄 설명}

## 배경

{문제 + 현재 프로세스를 서술형으로 정리}

## 안 하면 어떻게 되는가

{답변 정리. 정량 수치 포함}

## 사용자와 규모

{누가, 몇 명, 얼마나 자주}

## 성공 기준

{정량적 기준. 미확인 시 ❓ 표기}

## 담당자

| 역할 | 이름 | 비고 |
|------|------|------|
| PM/PO | {이름} | |
| 개발 리드 | {이름} | |

## 현재 상태

탐색 중

• 답변에서 ❓인 항목은 그대로 ❓로 남긴다.
• 사용자의 답변을 과도하게 다듬지 않는다. 핵심만 정리.

B-7. PROJECTS.md 작성

# {도메인명} 관련 프로젝트

| 레포 | 역할 | 담당 |
|------|------|------|
| {org/repo} | {역할} | {담당자} |

관련 레포가 없으면 빈 테이블로 생성한다.

B-8. glossary.md 작성

# {도메인명} 용어 사전

| 용어 | 설명 |
|------|------|

B-9. architecture.md 작성

# {도메인명} 아키텍처

> 전체 구조 요약과 주제별 상세 문서 링크를 관리합니다.

## 시스템 구조

(확정 시 작성)

## 주제 문서

| 주제 | 설명 |
|------|------|

B-9-1. status.md 작성

# {도메인명} 구현 추적

> PRD 요구사항별 구현 상태를 추적합니다.

## 범례

- ✅ 반영됨 — 코드에 구현 완료
- ⬜ 미반영 — 정책/설계만 확정, 코드 미구현

B-10. 인덱스 업데이트

context/README.md의 도메인 테이블에 새 행을 추가한다.

B-11. 완료 안내

생성된 파일 목록과 ❓ 항목(있다면)을 안내한다.

---

모드 C: 문서 기반 (--from)

PM이 정리한 텍스트 파일을 읽어서 context를 생성하거나 갱신한다.

C-1. 파일 읽기

--from 으로 지정된 파일을 Read한다.

• 지원 형식: .md, .txt, .pdf (PDF는 최대 20페이지)
• 이미지 파일(.png, .jpg): Read로 멀티모달 분석

C-2. 내용 분석

파일 내용에서 다음을 추출한다:

• 도메인명: 문서 제목이나 주제에서 추론. 인자로 도메인명이 지정되었으면 그것을 사용.
• 배경/문제: 프로젝트 배경, 현재 문제점
• 요구사항: 기능 요구사항, 비기능 요구사항
• 용어: 도메인 특화 용어와 정의
• 아키텍처: 시스템 구조, 기술 스택 언급
• 담당자: 문서에 명시된 담당자 정보

C-3. 추출 결과 요약 및 검증 질문

C-3-1. 추출 결과 요약 제시

문서에서 추출한 내용을 아래 형식으로 사용자에게 먼저 보여준다:

📄 문서 분석 결과

- 도메인명: {추론한 도메인명 또는 ❓}
- 배경/문제: {추출한 내용 요약 또는 ❓}
- 요구사항: {추출한 FR/NFR 수} 건
- 용어: {추출한 용어 수} 건
- 아키텍처: {추출 여부}
- 담당자: {추출한 정보 또는 ❓}

C-3-2. 검증 질문 라운드

추출 결과를 보여준 뒤, 아래 5개 항목 중 문서에서 충분히 파악되지 않은 항목을 AskUserQuestion으로 묻는다. 이미 문서에서 명확히 파악된 항목은 건너뛴다.

1. 문제: 이 도메인에서 풀려는 핵심 문제가 뭔가? (문서에서 추출한 내용이 있으면: "문서에서 이렇게 파악했는데 맞는가?" 형태로 확인)
2. 현재 프로세스: 지금은 어떻게 하고 있는가?
3. 사용자/규모: 예상 사용자와 규모는?
4. 담당: 이 도메인의 담당 PM/PO와 주요 개발자는?
5. 관련 레포: 관련 GHE 레포가 있는가?

질문 방식:

• 문서에서 이미 추출된 항목: "문서에서 '{추출 내용}'으로 파악했습니다. 맞나요? 보완할 내용이 있으면 알려주세요." (확인형)
• 문서에서 파악 안 된 항목: 모드 B-2와 동일하게 직접 질문 (개방형)
• 5개 항목을 한 번에 묻되, 확인형과 개방형을 구분하여 제시한다.

C-3-3. 답변 품질 판단

모드 B-3과 동일한 기준을 적용한다:

• 5개 중 3개 이상 구체적 → C-4로 진행
• 모호한 답변이 3개 이상 → 심화 질문 1라운드 추가 (B-3-1 절차와 동일)
• 여전히 모르는 항목은 ❓로 남기고 진행한다. 2라운드 이상 반복하지 않는다.

C-4. context 생성 또는 갱신

• context/{도메인}/이 없으면: 모드 B의 B-5~B-11 절차로 디렉토리와 문서를 생성한다. 다만 Q&A 답변 대신 파일에서 추출한 내용을 사용한다.
• context/{도메인}/이 이미 있으면: 모드 D(갱신)로 진행한다. 파일 내용과 기존 context를 비교하여 변경 제안을 생성한다.

---

모드 D: 갱신

기존 도메인의 context를 갱신한다.

D-1. 기존 문서 읽기

context/{도메인}/의 README.md, glossary.md, architecture.md를 Read한다.

D-2. 변경 소스 파악

• --from 파일이 있으면: 파일 내용과 기존 context를 비교하여 변경 항목을 식별한다.
• --from 없으면: AskUserQuestion으로 갱신 내용을 묻는다. "어떤 내용을 갱신하시겠습니까? (용어 추가, 아키텍처 변경, 담당자 변경 등)"

D-3. 변경 제안

변경 항목을 구체적으로 제안한다:

• "glossary.md에 '{용어}' 추가를 제안합니다."
• "README.md의 '배경' 섹션에 다음 내용 추가를 제안합니다: ..."
• "architecture.md에 '{컴포넌트}' 추가를 제안합니다."

D-4. 사용자 확인 후 반영

사용자가 승인한 변경만 Edit으로 반영한다. 문서 수정 시 수정일을 갱신한다.

---

모드 E: 동기화 (--sync)

/tddak:dev를 거치지 않고 개발한 내용을 git 히스토리에서 분석하여 status.md를 갱신한다.

--sync 사용 시 도메인명은 필수. 없으면 AskUserQuestion으로 도메인을 선택한다.

E-1. 사전 확인

1. context/{도메인}/status.md Read
2. ⬜ 항목이 0개면 → "갱신할 미반영 항목이 없습니다." 출력 후 종료
3. ⬜ 항목 목록을 파싱하여 PENDING_ITEMS 배열로 저장

E-2. git 히스토리 분석

1. git log --oneline -20으로 최근 커밋 20개 확인
2. gh pr list --state merged --limit 10으로 최근 머지된 PR 확인 (gh 없으면 건너뜀)
3. 커밋 메시지와 PR 제목에서 PENDING_ITEMS의 FR/AC/설명과 매칭되는 항목을 식별

E-3. 매칭 결과 제시

status.md 동기화 분석 결과:

  1. ✅ AC-1 (FR-1): 로그인 기능 — 커밋 a1b2c3d "feat: 로그인 기능 추가"
  2. ✅ AC-4 (FR-16): 비밀번호 변경 — PR #125 "FEATURE: 비밀번호 변경"
  3. ⬜ AC-2 (FR-2): 회원가입 — 매칭되는 커밋/PR 없음

위 항목을 반영할까요?

AskUserQuestion으로 확인. 사용자가 항목을 조정할 수 있다 (제외/추가).

E-4. status.md 갱신

사용자가 승인한 항목만 Edit으로 반영:

• ⬜ → ✅ 변경
• PR 열에 PR 링크 또는 커밋 해시 기입
• 수정일 갱신

E-5. 완료 안내

status.md 갱신 완료: ✅ {N}건 반영 (AC-1, AC-4)
남은 미반영: ⬜ {M}건

---

주제 문서 헤더 템플릿

아래는 /tddak:dev 환류 등으로 주제 문서를 생성할 때 사용하는 헤더 형식이다. /tddak:context 실행 시에는 생성하지 않는다.

# {제목}

- 작성일: YYYY-MM-DD
- 수정일: YYYY-MM-DD
- 관련 레포: {org/repo}