Code Generation

언제 사용하나요

다음 상황에서 본 skill을 실행합니다.

• component-design skill이 생성한 design.md가 리뷰어 승인을 받은 직후
• 기존 컴포넌트에 새 기능을 추가하는 코드 생성이 필요할 때 (설계 변경분은 component-design으로 재작성)
• test-strategy skill이 먼저 작성한 실패 테스트를 통과시키는 구현 단계(TDD 흐름)

다음 상황에서는 사용하지 않습니다.

• design.md가 아직 승인되지 않은 상태 — 승인 전 코드 생성은 계약 위반을 유발합니다.
• 프로덕션 핫픽스 — 설계 문서 갱신 없이 긴급 수정이 필요한 경우 팀 규약에 따라 직접 패치 후 사후 문서화합니다.
• 대규모 리팩토링(컴포넌트 경계 변경) — 먼저 component-design으로 설계 재작성이 필요합니다.

전제 조건

• .omao/plans/construction/design.md 존재 및 리뷰어 승인 기록(aidlc-docs/audit.md) 완료.
• 대상 코드 베이스의 주 언어 런타임 설치(Python 3.11+ 또는 Node.js 20+ 등).
• 린터·포매터 설정 파일 존재(pyproject.toml, ruff.toml, .eslintrc 등).
• Git 저장소 clean 상태 — uncommitted 변경이 있으면 실행 거부.
• .omao/plans/construction/rollback/ 디렉토리 쓰기 권한.

실행 절차

Step 1: design.md 계약 파싱

design.md의 Interfaces 섹션에서 타입 서명과 예외 계약을 추출하여 체크리스트로 변환합니다.

DESIGN=.omao/plans/construction/design.md
test -f "$DESIGN" || { echo "design.md missing"; exit 1; }
grep -qE "^## Interfaces" "$DESIGN" || { echo "Interfaces section missing"; exit 1; }

각 인터페이스에 대해 다음을 태스크 리스트로 기록합니다: 서명, 예외, 멱등성, 호출자, 호출 대상.

Step 2: 코드 생성 계획 작성

.omao/plans/construction/code-plan.md를 작성합니다. 다음 단계로 분할합니다.

1. Project Structure Setup — 디렉토리·패키지·의존성 추가
2. Interface Stubs — Protocol·interface 파일 생성 (구현 없음)
3. Data Model — Pydantic·SQLAlchemy·Prisma 스키마
4. Tool Implementations — 결정적 컴포넌트 먼저 구현
5. Agent Implementation — LLM 호출 포함 컴포넌트 구현
6. Gateway Integration — 라우팅·guardrail 연결
7. Documentation — README·docstring·OpenAPI

각 단계는 별도 커밋으로 분리하여 리뷰 단위를 작게 유지합니다.

Step 3: 롤백 스냅샷 생성

코드 수정 대상 파일을 현재 상태 그대로 .omao/plans/construction/rollback/에 보관합니다.

STAMP=$(date +%Y%m%d-%H%M%S)
mkdir -p ".omao/plans/construction/rollback/${STAMP}"
git diff --name-only main -- . | xargs -I{} sh -c 'mkdir -p ".omao/plans/construction/rollback/${STAMP}/$(dirname {})" && cp {} ".omao/plans/construction/rollback/${STAMP}/{}"'

롤백 경로는 eval regression 또는 리뷰 반려 시 즉시 복원에 사용합니다.

Step 4: 스캐폴딩 및 템플릿 기반 생성

정형화된 코드(Pydantic 모델, API 핸들러 뼈대, 테스트 스텁)는 템플릿으로 생성합니다. 자유 서술이 필요한 로직(프롬프트 구성, 복잡한 제어 흐름)은 설계 문서 근거를 명시적으로 참조하여 작성합니다.

템플릿 예시 — Tool 구현 스텁:

# src/tools/retrieval.py
from typing import Sequence
from src.contracts import RetrievalTool, RetrievalResult

class MilvusRetrievalTool(RetrievalTool):
    def __init__(self, collection: str) -> None:
        self._collection = collection

    def search(self, query: str, top_k: int) -> Sequence[RetrievalResult]:
        raise NotImplementedError("implement in Step 4.2")

Step 5: 계약 위반 자동 검증

생성 완료 후 다음 정적 검증을 수행합니다. 하나라도 실패하면 해당 커밋을 되돌립니다.

• 타입 검사 — mypy --strict 또는 tsc --noEmit
• 린트 — ruff check 또는 eslint
• 포맷 — ruff format --check 또는 prettier --check
• 인터페이스 일치 — design.md의 Protocol 서명과 실제 구현 서명 diff 없음

ruff check . && ruff format --check . && mypy --strict src/

Step 6: 사람 승인 gate 제출

변경 사항을 feature branch에 커밋하고 PR을 Draft로 생성합니다. main에 직접 푸시하거나 auto-merge를 설정하지 않습니다.

BRANCH="construction/${UNIT}-$(date +%Y%m%d-%H%M)"
git checkout -b "$BRANCH"
git add .
git commit -m "feat(${UNIT}): scaffold interfaces and data model per design.md"
gh pr create --draft \
  --title "feat(${UNIT}): Construction implementation" \
  --body "Implements design.md §2 §3. Rollback at .omao/plans/construction/rollback/${STAMP}/"

리뷰어 승인 없이 머지되지 않도록 repository의 branch protection 설정을 사용합니다.

Step 7: Eval 연동 준비

test-strategy skill이 eval suite를 실행할 수 있도록 entry point를 노출합니다. tests/eval/run.py 또는 Makefile target(make eval)이 존재해야 합니다. 존재하지 않으면 stub을 생성하고 test-strategy skill로 실행을 위임합니다.

Good Example vs Bad Example

Good — 결정적 Tool을 먼저 구현하여 독립 unit test가 가능합니다.

class DeterministicHashTool:
    def compute(self, text: str) -> str:
        return hashlib.sha256(text.encode()).hexdigest()

Bad — LLM 호출이 Tool 내부에 숨겨져 mock 지점이 불명확합니다.

class SummaryTool:
    def run(self, text: str) -> str:
        return anthropic.Anthropic().messages.create(...)  # LLM 호출 직접 매립

Good — PR이 Draft 상태이고 설계 근거가 본문에 명시되어 있습니다.

Bad — main에 직접 푸시했으며 설계 문서 링크가 없습니다.

산출물 체크리스트

본 skill 실행 종료 직전 다음을 자동 검증합니다.

• .omao/plans/construction/code-plan.md 존재
• .omao/plans/construction/rollback/${STAMP}/ 스냅샷 생성
• 타입 검사·린트·포맷 통과
• design.md Interfaces와 구현 서명 일치
• PR이 Draft 상태로 생성, main 직접 푸시 없음
• aidlc-docs/audit.md에 제출 기록

참고 자료

공식 문서

• awslabs/aidlc-workflows — code-generation.md — Construction code generation 규약
• pytest Documentation — 테스트 프레임워크
• ruff Documentation — Python 린터·포매터
• GitHub CLI gh pr create — Draft PR 생성

관련 문서 (내부)

• component-design skill — 본 skill의 선행 실행자
• test-strategy skill — 본 skill의 병렬 검증자
• tdd-for-agentic opt-in — Construction 테스트 규칙