task-definition-generator

Task Definition Generator

사용자의 Task 요청을 분석하고, 코드베이스를 탐색하여 구조화된 Task Definition 문서를 생성합니다.

Overview

Task 유형(API 추가 / 기능 개선 / 버그 수정)은 최종 output의 분류 라벨이다. 분석 범위는 유형이 아닌 Task 내용 자체가 결정한다.

---

처리 흐름

Step 1: Task 내용 이해

사용자의 요청에서 핵심 정보를 파악한다:

• 대상 도메인: 어떤 기능/모듈에 관한 것인가?
• 행위: 추가/수정/삭제/개선 중 무엇인가?
• 키워드: 검색에 사용할 핵심 용어 (클래스명, API 경로, 기능명 등)

Step 2: 코드베이스 탐색

Task 키워드를 기반으로 관련 파일을 동적으로 탐색한다.

탐색 원칙:

1. 키워드 기반 검색: Grep으로 관련 클래스/함수/라우터/경로 검색
2. 도메인 파일 매칭: Glob으로 관련 도메인 파일 패턴 매칭
3. 핵심 파일 확인: Read로 주요 파일 내용 파악
4. 계층 추적 (하향식): 영향 범위를 아래 계층으로 확장
   • 예: Service 수정 → 의존하는 Repository 확인
   • 예: Model 변경 → 해당 모델 사용하는 Repository, Schema 확인
5. 역방향 추적 (상향식): 변경의 영향을 받는 상위 계층 및 관련 파일 확인
   • 호출자 역추적: Grep으로 함수/클래스명을 검색하여 호출하는 위치 파악
   • 기존 테스트 역추적: test_*.py 패턴으로 영향 받는 테스트 파일 확인
   • import 역추적: 변경 모듈을 import하는 파일 검색

탐색 범위는 Task 내용에 따라 다르다. 고정된 유형별 템플릿을 따르지 않는다.

검색 결과가 없을 때:

1. 검색 키워드를 동의어/유사어로 확장하여 재탐색
2. 여전히 없으면 완전히 새로운 기능으로 판단하고, 모든 파일을 "생성"으로 분류
3. 기존 유사 도메인의 파일 구조를 참고하여 신규 파일 목록 작성

Step 3: 영향 분석 정리

탐색 결과를 정리한다:

• 영향 받는 파일: 기존 수정 대상 + 신규 생성 필요 파일
• 의존성: 다른 모듈/서비스와의 관계
• 작업 유형: 각 파일에 대해 생성/수정 구분

Step 4: Task 유형 라벨링

분석 결과를 바탕으로 가장 적합한 유형을 분류한다:

유형	판단 기준
API 추가	새로운 엔드포인트/라우트가 필요한 경우
기능 개선/수정	기존 기능의 동작을 변경/확장하는 경우
버그 수정	기존 기능의 오류를 수정하는 경우

Step 5: Task Definition 생성

아래 출력 형식으로 Task Definition을 생성한다.

---

사용자 상호작용

다음 상황에서 AskUserQuestion을 사용한다:

• 범위 모호: Task 대상이 여러 모듈에 걸칠 수 있을 때
• 영향 범위 확인: 예상보다 넓은 영향이 감지되었을 때 포함/제외 확인
• 우선순위: 여러 수용 기준 중 필수/선택 구분이 필요할 때

---

출력 형식

## Task Definition

### 유형
[API 추가 | 기능 개선/수정 | 버그 수정]

### 요약
[한 줄 요약]

### 목표
[달성해야 할 결과물]

### 범위
- 포함: [...]
- 제외: [...]

### 기술적 요구사항
- [요구사항 1]
- [요구사항 2]

### 수용 기준 (Acceptance Criteria)
- [ ] AC-1: [구체적이고 검증 가능한 조건]
- [ ] AC-2: [구체적이고 검증 가능한 조건]
- [ ] AC-3: [구체적이고 검증 가능한 조건]

### 영향 분석

#### 영향 받는 파일
| 파일 경로 | 작업 유형 | 설명 |
|-----------|----------|------|
| src/controllers/xxx.py | 생성 | [설명] |
| src/services/xxx_service.py | 수정 | [설명] |

#### 의존성
- [의존성 1: 예) 기존 ResearchRepository.get_list 메서드]
- [의존성 2: 예) containers.py DI 등록 필요]

---

수용 기준 작성 원칙

• 각 기준에 AC-N 식별자 부여 (Plan Generator가 매핑에 사용)
• 식별자 형식 규칙:
  • 형식: AC-[숫자] (예: AC-1, AC-2, ..., AC-10)
  • 번호는 1부터 시작하며 연속적으로 부여 (건너뛰기 불가)
  • zero-padding 없이 자연수로 표기 (AC-10, AC-01 아님)
• 구체적이고 검증 가능하게 작성
• 좋은 예: AC-1: GET /api/researches/{id}/favorites 호출 시 200 응답과 즐겨찾기 목록 반환
• 나쁜 예: AC-1: API가 잘 동작한다

---

주의사항

• 코드베이스를 실제로 탐색한 결과를 기반으로 영향 파일을 작성한다. 추측하지 않는다.
• 존재하지 않는 파일은 "생성"으로, 기존 파일은 "수정"으로 명확히 구분한다.
• 영향 분석의 "의존성" 항목에는 구체적인 클래스명/메서드명을 포함한다.
• 영향 받는 파일에 테스트 파일(tests/)을 포함하지 않는다. 테스트는 워크플로우 Phase 4에서 /test 커맨드가 전담하므로, Task Definition과 Plan의 범위 밖이다.