애드혹 구현 계획

애드혹 구현 계획은(는) 무엇을 하나요?

대략적인 아이디어에서 구현-커밋 준비가 완료된 산출물로 빠르게 전환합니다. 문서 완성도보다 속도에 중점을 둡니다.

사용 시기

• 사용자와 논의한 대략적인 계획이나 아이디어가 있을 때
• 정식 propose-* 체인 없이 implement-commit의 TDD 검증을 원할 때
• 기능을 충분히 이해하여 광범위한 설계 반복을 생략할 수 있을 때

전제 조건

• 사용자가 승인한 대략적인 계획 (대화, 마크다운, 또는 머릿속 구상 가능)
• 알려진 워크스페이스 경로
• 수정할 파일 목록

오케스트레이터 역할

당신은 기계적인 라우터입니다. 기능에 대해 생각하지 않습니다. 당신의 임무:

1. 사용자로부터 필요한 최소 정보 수집
2. 기능 디렉터리 구조 생성
3. 적절한 스킬을 컨텍스트로 하위 에이전트 실행
4. 단계 간 출력 전달
5. 상호 참조 검증

설정

from pydantic import BaseModel
from pathlib import Path
import os

class GatherResult(BaseModel):
    feature_name: str
    feature_id: str  # NNNN 형식
    workspace: str
    files_to_modify: list[str]
    constraints: list[str]
    test_names: list[str]
    rough_plan_summary: str

class PhaseResult(BaseModel):
    success: bool
    artifact_path: str
    errors: list[str]

# 하위 에이전트 컨텍스트용 스킬 경로
skills = {
    "design": "skills/propose-feature-design/SKILL.md",
    "test_plan": "skills/propose-feature-test-plan/SKILL.md",
    "impl_plan": "skills/propose-implementation-plan/SKILL.md",
}

# 스타일 가이드 (있는 경우)
style_guides = [
    "docs/style/rust-design.md",
    "docs/style/rust-test.md",
    "docs/style/rust-impl.md",
]

0단계: 수집(Gather)

대략적인 계획에서 대화형으로 수집하거나 추론합니다:

# 아직 알려지지 않은 경우 사용자에게 질문:
# 1. 기능 이름 → docs/features/NNNN-name/ 생성
# 2. 수정할 파일 → commits[].files
# 3. 주요 제약 조건 → CC 테이블 항목
# 4. 테스트 이름 → test-plan + commits[].tests

# 다음 기능 ID 결정
existing = list(Path("docs/features").glob("[0-9][0-9][0-9][0-9]-*"))
next_id = f"{len(existing):04d}"

feature_dir = f"docs/features/{next_id}-{feature_name}"
os.makedirs(feature_dir, exist_ok=True)

1단계: 최소 설계(Minimal Design)

propose-feature-design 스킬로 하위 에이전트를 실행하되, 최소 출력을 지시합니다.

result = spawn(
    prompt=draft_spawn_prompt(SkillDefined(
        "스킬 절차에 따라 MINIMAL design.md를 생성하십시오. "
        "다음만 생성: 개요(1문단), 중요 제약 조건 테이블, 모듈 구조. "
        "건너뛸 것: 아키텍처 다이어그램, 솔루션 메커니즘 설명, 디자인 패턴, 설계 결정."
    )),
    context_files=[
        skills["design"],
        *[g for g in style_guides if exists(g)],
    ],
    context_data={
        "feature_dir": feature_dir,
        "feature_name": gathered.feature_name,
        "constraints": gathered.constraints,
        "files": gathered.files_to_modify,
        "rough_plan": gathered.rough_plan_summary,
        "minimal_mode": True,
    },
    response_model=PhaseResult,
    isolate_to=Cwd(gathered.workspace)
)

2단계: 최소 테스트 계획(Minimal Test Plan)

propose-feature-test-plan 스킬로 하위 에이전트를 실행합니다.

result = spawn(
    prompt=draft_spawn_prompt(SkillDefined(
        "스킬 절차에 따라 MINIMAL test-plan.md를 생성하십시오. "
        "다음만 생성: 요구사항 커버리지 테이블, 중요 제약 조건 검증 테이블. "
        "건너뛸 것: 상세 테스트 구현 노트, 통합 테스트 설명."
    )),
    context_files=[
        skills["test_plan"],
        f"{feature_dir}/design.md",  # 1단계 결과물
        *[g for g in style_guides if exists(g)],
    ],
    context_data={
        "feature_dir": feature_dir,
        "test_names": gathered.test_names,
        "constraints": gathered.constraints,
        "minimal_mode": True,
    },
    response_model=PhaseResult,
    isolate_to=Cwd(gathered.workspace)
)

3단계: 구현 계획(Implementation Plan)

propose-implementation-plan 스킬로 하위 에이전트를 실행합니다.

result = spawn(
    prompt=draft_spawn_prompt(SkillDefined(
        "스킬 절차에 따라 implementation-plan.toml을 생성하십시오. "
        "모든 필드는 필수 - 최소 모드 없음. "
        "tests[]가 test-plan.md의 테스트 이름과 정확히 일치하는지 확인하십시오."
    )),
    context_files=[
        skills["impl_plan"],
        f"{feature_dir}/design.md",
        f"{feature_dir}/test-plan.md",
        *[g for g in style_guides if exists(g)],
    ],
    context_data={
        "feature_dir": feature_dir,
        "workspace": gathered.workspace,
        "files": gathered.files_to_modify,
        "rough_plan": gathered.rough_plan_summary,
    },
    response_model=PhaseResult,
    isolate_to=Cwd(gathered.workspace)
)

4단계: 상호 참조 검증(Verify Cross-References)

테스트 커버리지를 검사하는 검증기를 실행합니다.

class VerifyResult(BaseModel):
    valid: bool
    missing_tests: list[str]  # test-plan에 있지만 impl-plan에 없는 경우
    orphan_tests: list[str]   # impl-plan에 있지만 test-plan에 없는 경우
    missing_constraints: list[str]  # CC-N이 커버되지 않은 경우

result = spawn(
    prompt=draft_spawn_prompt(AdHoc(
        intents=["implementation-plan.toml이 implement-commit에 유효한지 검증"],
        context=["산출물 간 모든 상호 참조 확인"],
        goal=Verify(constraints=[
            "test-plan.md의 모든 테스트가 commits[].tests에 정확히 한 번 나타남",
            "design.md의 모든 CC-N이 test-plan.md에서 검증됨",
            "모든 commits[].files가 존재하거나 생성될 예정임",
            "TOML이 올바르게 파싱됨",
        ])
    )),
    context_files=[
        f"{feature_dir}/design.md",
        f"{feature_dir}/test-plan.md",
        f"{feature_dir}/implementation-plan.toml",
    ],
    response_model=VerifyResult,
    read_only=True
)

if not result.parsed.valid:
    # 오류와 함께 3단계로 복귀
    pass

핸드오프

검증이 완료되면 산출물이 implement-commit에 사용할 준비가 됩니다:

docs/features/NNNN-feature-name/
├── design.md              # 최소: 개요 + CC 테이블 + 모듈 구조
├── test-plan.md           # 최소: 커버리지 테이블만
└── implementation-plan.toml  # 전체: 모든 필수 필드

사용자에게 알림:

산출물이 준비되었습니다. implement-commit 스킬을 실행하여 TDD 파이프라인을 진행하세요.