# ADK Implementation Spec #10: Task 파일 구조 표준화

**문서 ID**: adk-impl-spec-10
**DRI**: 오딘 (2팀장)
**작성일**: 2026-04-01
**상태**: 파일럿 진행 중
**관련 계획서**: `/home/jay/workspace/memory/plans/moai-adoption/plan.md`

---

## 1. 현황 분석 (2026-04-01 기준)

### 1.1 파일 통계

- 파일 총 수: 2,230개
- 번호형 task (`task-{번호}.{체인}.md`): 1,193개 (53.5%)
- dispatch형 (`dispatch-{식별자}.md`): 902개 (40.4%)
- 비표준: 59개 (2.6%) — `ad-creative-*.md`, `test-*.md`, `pending-*.md`, `테스트 작업.md` 등
- handoff 파일: 47개
- phase-plan 파일: 26개
- YAML frontmatter 보유: 0/20 샘플 (0%)
- 가장 긴 파일명: 57자 (`task-100.3: 감사 개선 — 대시보드 횡단조직 memberStatus + 패스워드 하드코딩 제거`)
- 가장 짧은 파일명: 5자 (`t1.md`)
- 공백 포함 파일명: 4개 (`테스트 작업.md`, `task-100.3: ...`, `## 개선계획서`, `test task.md`)
- 한글 파일명: 1개 (`테스트 작업.md`)
- 대문자 포함: 8개 (`dispatch-content-structure-phaseB.md`, `task-TEST.1.md` 등)
- 특수문자(`:`) 포함: 1개 (`task-100.3: ...`)
- 빈 파일: 0개

### 1.2 문제점

- YAML frontmatter 부재: 2,230개 파일 중 frontmatter 보유율 0%. 오케스트레이터가 task를 파싱할 때 본문을 읽어야 팀/우선순위를 알 수 있음.
- 비표준 파일명: 59개(2.6%)가 공식 네이밍 규칙 없이 생성됨. 공백, 한글, 대문자, 특수문자 포함.
- 메타데이터 미분리: task 속성(팀, 레벨, 우선순위)이 본문에 산재하여 자동화 불가.

---

## 2. YAML Frontmatter 스키마

### 2.1 필수 필드

```yaml
---
task_id: "1285.1"          # task 고유 ID
                            # 번호형: {번호}.{체인번호} (예: "1285.1")
                            # dispatch형: dispatch-{식별자} (예: "dispatch-moai-phase1")
team: "2팀"                 # 담당 팀. 값: 1팀/2팀/3팀/4팀/QC/전략/DA/오케스트레이터
level: 4                    # 위임 레벨. 정수 1-4
priority: "P1"              # 우선순위. 값: P1/P2/P3/P4
depends_on: []              # 선행 task_id 목록. 없으면 빈 배열
created_at: "2026-03-31"   # 생성일. ISO 8601 날짜
deadline: "2026-04-14"     # 데드라인. ISO 8601 날짜. 없으면 null
---
```

### 2.2 선택 필드

```yaml
---
status: "in_progress"       # 상태. 값: pending/in_progress/done/blocked
dri: "헤르메스"              # 단독 책임자
tags: ["hooks", "P1"]       # 자유 태그 목록
spec_doc: "/memory/specs/adk-impl-spec-7.md"  # 연관 스펙 문서 경로
---
```

### 2.3 스키마 제약 조건

- YAML 블록은 파일 최상단 첫 줄에서 시작 (앞 공백 없음)
- `task_id` 값은 파일명과 일치해야 함 (`task-1285.1.md` → `"1285.1"`, `dispatch-moai-phase1.md` → `"dispatch-moai-phase1"`)
- `depends_on`이 없는 경우 `[]` (null 금지)
- `deadline`이 없는 경우 `null` (빈 문자열 금지)
- `team` 값은 정해진 목록 중 하나여야 함

### 2.4 설계 근거

- `task_id`: 파일명에서 추출 가능 → 파일 탐색 O(1)
- `team`: 오케스트레이터가 라우팅 시 파일 내부를 파싱하지 않아도 됨
- `level`: 위임 레벨별 모델 선택 자동화 근거
- `depends_on`: 병렬 실행 시 의존성 체크 자동화 가능
- `created_at` / `deadline`: 타임라인 추적 + staleness 감지

---

## 3. 네이밍 규칙

### 3.1 표준 형식

- 번호형 task: `task-{번호}.{체인번호}.md` (예: `task-1285.1.md`)
- dispatch 지시서: `dispatch-{식별자}.md` (예: `dispatch-moai-phase3.md`)
- handoff 파일: `task-{번호}.{체인번호}-handoff-{n}.md` (예: `task-1285.1-handoff-1.md`)
- phase 계획: `task-{번호}.{체인번호}-phase-plan.md` (예: `task-1285.1-phase-plan.md`)

### 3.2 금지 규칙

- 공백 포함 파일명 금지 (`테스트 작업.md` → `task-test-work.md`)
- 한글 파일명 금지 (탐색 시 인코딩 오류 위험)
- 대문자 포함 금지 (`Task-1000.md` → `task-1000.md`)
- 특수문자(`:`, `?`, `*`) 파일명 포함 금지

### 3.3 현재 위반 파일 (정리 대상)

- 공백 포함: 4개 (`테스트 작업.md`, `test task.md` 등)
- 한글: 1개 (`테스트 작업.md`)
- 대문자: 8개 (`dispatch-content-structure-phaseB.md` 등)
- 특수문자: 1개 (`task-100.3: 감사 개선...`)
- 비표준 접두사: ~45개 (`ad-creative-*.md`, `test-*.md`, `pending-*.md` 등)

---

## 4. 파일럿 적용

### 4.1 대상 파일 (5개)

1. `task-1285.1.md` — MoAI-ADK 10개 도입 항목 미팅 (번호형, 74줄)
2. `task-1284.1.md` — MoAI-ADK 심층 분석 리서치 (번호형, 53줄)
3. `task-1283.1.md` — 캠페인뷰 전략 문서 동적 파일 스캔 (번호형, 59줄)
4. `dispatch-moai-phase1.md` — MoAI-ADK Phase 1 코드화 지시서 (dispatch형, 879줄)
5. `dispatch-moai-adk-research.md` — MoAI-ADK 심층 분석 리서치 (dispatch형, 54줄)

### 4.2 적용 결과 (2026-04-01 실행)

- `task-1285.1.md`: 필수 7필드 + 선택 3필드(status, dri, tags) 삽입 완료. task_id="1285.1" ✓
- `task-1284.1.md`: 필수 7필드 + 선택 3필드(status, dri, tags) 삽입 완료. task_id="1284.1" ✓
- `task-1283.1.md`: 필수 7필드 + 선택 2필드(status, tags) 삽입 완료. task_id="1283.1" ✓
- `dispatch-moai-phase1.md`: 필수 7필드 + 선택 4필드(status, dri, tags, spec_doc) 삽입 완료. task_id="dispatch-moai-phase1" ✓
- `dispatch-moai-adk-research.md`: 필수 7필드 + 선택 3필드(status, dri, tags) 삽입 완료. task_id="dispatch-moai-adk-research" ✓

발견 사항:
- 기존 본문 변경 없이 YAML 블록만 상단 삽입 → 기존 워크플로우와 충돌 없음
- dispatch형 파일의 task_id는 `dispatch-{식별자}` 형식으로 파일명과 1:1 매칭 확인
- 번호형 파일의 task_id는 `{번호}.{체인번호}` 형식으로 파일명에서 `task-` 접두사 제외 후 매칭 확인

### 4.3 완료 기준 (DoD)

- [x] 5개 파일 전부 YAML frontmatter 삽입 완료
- [x] 각 파일의 `task_id` 값이 파일명과 일치
- [x] 스펙 문서 작성 완료 (본 문서)
- [x] 파일럿 결과 검토: frontmatter 누락 필드 없음
- [x] DIRECT-WORKFLOW.md에 네이밍 규칙 섹션 추가

---

## 5. P4 자동화 전망

본 스펙 파일럿 완료 후, Week 8 평가에서 아래 P4 항목 재논의:
- `task-gen` CLI: task 파일 자동 생성 도구
- YAML frontmatter 자동 삽입 스크립트
- 기존 파일 일괄 마이그레이션 도구

---

## 변경 이력

- 2026-04-01: v1.0 초안 작성 (오딘)