ADD(AI-driven Document Development Pipeline) 개발 방법론 정의

0. Introduction: Engineering the Agent's Mind

이 파이프라인은 단순히 문서를 남기기 위한 절차가 아닙니다. 불완전한 확률적 도구인 AI(LLM)를 신뢰할 수 있는 결정론적 엔지니어(Deterministic Engineer)로 변환하기 위한 구조적 통제 장치입니다.

 

우리는 AI의 코딩 능력이 부족해서 실패하는 것이 아니라, **'오염된 맥락(Context Pollution)'**과 '과도한 인지 부하(Cognitive Overload)' 때문에 실패한다는 사실을 직시해야 합니다. ADD Pipeline은 다음 4가지 핵심 원칙을 통해 이 문제를 해결합니다.

1. Code is a Transient Derivative (코드는 파생물이다)

코드는 문서가 실행 가능한 형태로 번역된 일시적인 결과물에 불과합니다. 지혜, 구조, 그리고 결정은 변경이 잦은 코드가 아니라, **변경 빈도가 낮은 문서(Static Docs)**에 저장되어야 합니다. 이것이 곧 Agent에게 제공될 고정불변의 Context가 되며, 코드를 언제든 재생산할 수 있는 원천(Source)이 됩니다.

 

2. Minimum Cognitive Load (인지 부하의 최소화)

"설계하고, 구현하고, 검증하라"를 한 번에 지시하는 것은 AI에게 환각(Hallucination)을 강요하는 것입니다. 우리는 개발 프로세스를 **[추상] → [구체] → [뼈대] → [구현]**의 단계로 철저히 분리합니다. 각 단계에서 Agent는 오직 하나의 목표에만 집중하며, 이전 단계의 산출물(Artifact)을 다음 단계의 입력으로 사용하여 논리적 단절을 방지합니다.

 

3. Strict Verification Protocol (객관적 검증)

"잘 작동하는 것 같아요"라는 주관적 평가는 허용되지 않습니다. 모든 구현은 자연어 명세(Spec)와 1:1로 매핑되는 체크리스트와 테스트 코드를 통과해야 합니다. 우리는 Agent가 작성한 코드를 신뢰하지 않으며, 오직 Agent가 통과시킨 테스트 결과만을 신뢰합니다.

 

4. Context Hygiene & Atomic Sessions (컨텍스트 위생 관리)

AI의 기억은 유한하며, 대화가 길어질수록 성능은 기하급수적으로 하락합니다.

• Context Engineering: 작업 시작 시, system_architecture.md와 같은 핵심 문서와 해당 작업에 필요한 최소한의 파일만을 로딩하여 최적의 상태를 구성합니다.
• Atomic Session: 하나의 작업(Task)은 하나의 세션(Session)에서 수행하고 종료합니다. 세션이 종료되면 오염된 대화 기록(Chat History)은 폐기되며, 오직 결과물(Code, Doc)만이 남습니다.

 

1. Core Artifacts Structure (문서/프로젝트 관리 체계)

개발 시작 전, 숲을 지탱할 정보의 저장소가 먼저 정의되어야 합니다.

• docs/system_architecture.md : 시스템의 거시적 설계, 데이터 흐름, 핵심 구성 요소 정의.
• docs/components/ : 시스템의 주요 컴포넌트 각각의 마이크로서비스 정도로 봐도 됨.
• docs/adr/s : 왜 이 기술을 썼는지, 왜 이 구조를 택했는지에 대한 의사결정 기록 (ADR).
• docs/impl_specs/{implemenation_name}_impl_spec.md : 실제 구현을 위한 상세 명세, 구현을 위한 디테일, 체크리스트, 클래스 구조, 함수 시그니처, 엣지 케이스 등이 작성됨.
• work_queue/worklog_list.json (작업 지시서): 구현해야 할 기능들을 더 이상 쪼갤 수 없는 **원자 단위(Atomic Unit)**로 분해하여 관리합니다. 에이전트가 한 번에 너무 많은 맥락을 처리하다 실패하는 것을 방지합니다.
• work_queue/progress.md (작업 일지): 현재 진행 중인 작업의 스냅샷입니다. 에이전트의 컨텍스트 윈도우 한계를 극복하기 위해, 최근 10개 세션의 핵심 변경 사항과 디버깅 기록만을 요약하여 유지합니다.
• docs/history_architves/ : 완료된 작업의 요약본을 선형적으로 기록하여, 프로젝트가 어떻게 발전해왔는지에 대한 거시적 흐름을 보존합니다.
• prompts/ : 자주 반복되는 작업(Skeleton 생성, Test 코드 작성, 리팩토링 등)을 수행하기 위한 정형화된 프롬프트 템플릿 모음입니다.

---

2. The 4-Stage Macro Flow (거시적 개발 단계)

전체 흐름은 [추상(토론)] → [구체(문서)] →[뼈대(Skeleton) 및 테스트] → [살(Implementation)]의 4단계로 흐릅니다.

Stage 1. Definition & Decision (정의 및 결정)

"생각을 확정하는 단계"

• Trigger: "이런 기능을 만들어야겠다"는 아이디어 발생.
• Process (Human + AI):
  1. 토론: AI와 기능의 범위, 기술적 실현 가능성, 사이드 이펙트 토론.
  2. 의사결정: DB 스키마 변경, API 구조, 사용할 라이브러리 등 핵심 사항 결정.
• Output (Artifacts):
  • system_architecture.md
  • {component_name}_component.md

Stage 2. Blueprinting (청사진 설계)

"구현의 지도를 그리는 단계"

• Process:
  1. 상세 설계: Stage 1의 결정을 바탕으로 실제 구현 레벨의 디테일(체크리스트, 클래스명, 메서드명, 파라미터 타입)을 설계.
  2. 문서화: 이를 **docs**/**impl_specs/**에 정리.
  3. Skeleton Code 작성: AI를 통해 껍데기 코드(Interface, Type, Empty Class) 및 구현 디테일을 코드의 주석으로 생성(변경될 여지가 있으므로)
  4. 테스트 코드 작성: Unit Test and Integration Test 를 생성
• Output (Artifacts):
  • {implemenation_name}_impl_spec.md (상세 명세서)
  • src/**/*.ts (Skeleton Codes - 로직 없음)
  • tests/**/*.ts : (Test Code 명세들)

Stage 3. Verification & Hardening (검증 및 강화)

"실패할 수 없는 환경을 만드는 단계"(모든 Agent 의 작업은 검증이 뒤따른다.)

 

Process 1: Spec-Driven Verification (명세 기반 검증)

"자연어 명세(Spec)와 코드(Test)의 1:1 매핑"

• 체크리스트 매핑 (Checklist Mapping):
  • docs/specs/xxx.md에 정의된 '구현 체크리스트' 항목들이 테스트 코드의 describe/it 블록으로 빠짐없이 변환되었는지 확인.
  • Agent는 "명세서의 항목 1번이 테스트 파일의 15번째 줄에 구현되었습니다"라는 리포트를 제출해야 함.

 

Process 2: Advanced Strategy for Oracle Problem (고급 검증 기법)

"정답을 미리 알기 힘든 복잡한 로직을 위한 수학적 검증"

Agent가 작성한 로직이 맞는지 사람이 일일이 계산하기 힘들 때, 다음의 객관적 검증 기법을 테스트 코드에 심습니다.

1. 속성 기반 테스트 (Property-based Testing):
   • 특정 입력값이 아니라, **"입력값이 변해도 변하지 않는 불변의 법칙(Invariant)"**을 검증.
   • 예: 정렬 알고리즘 구현 시, sort(list)의 결과는 항상 length가 같아야 하며, 모든 요소는 i <= i+1이어야 한다. (구체적 값 검증 아님)
   • 도구: fast-check (TS), Hypothesis (Python) 등 활용.
2. 역함수 기법 (Inverse Function / Round-trip Verification):
   • 결과값을 예측하기 힘들 때, 원래대로 되돌렸을 때(Inverse) 입력값과 같은지 확인.
   • 예: JSON.parse(JSON.stringify(data)) === data
   • 예: decrypt(encrypt(message)) === message
   • Agent에게 인코더를 구현하라고 했다면, 검증은 디코더를 통해 원복 여부로 판단.
3. 변성 테스트 (Metamorphic Testing):
   • 입력을 변화시켰을 때, 출력도 예상 가능한 관계를 유지하는지 검증.
   • 예: 검색 엔진에서 keyword로 검색한 결과 집합은, keyword + filter로 검색한 결과 집합을 포함해야 한다(Subset).

 

Process 3: Worklog Definition (작업 큐 확정)

• 위의 검증 기준(테스트 코드 + 정적 분석 규칙)을 통과하는 것을 **Complete Condition(완료 조건)**으로 설정하여 worklog_list.json에 해당 작업을 pass 했다고 기록.

 

Stage 4. Atomic Implementation Loop (원자적 구현)

"실제로 코드를 채워 넣는 단계" (이전에 설계한 Micro Flow가 여기서 작동)

• Process (반복 루프):
  1. Context Loading: worklog_list.json에서 작업 하나를 꺼내고, 관련 문서(ARCH, SPECS)와 git log를 로딩. (작업과 관련된 문서 및 코드를 찾아서 취합 후 컨택스트로 로딩)
  2. Implementation: 실제 로직 구현.
  3. Validation:
     • Objective: 테스트 모듈 실행 (Pass/Fail).
     • Subjective: Critic Agent가 설계 문서(SPECS) 준수 여부 검사.
  4. Commit & Log: 검증 통과 시 git commit 및 progress.md 기록. (세션 종료. 하나의 작업은 하나의 세션만 유지)
• Output (Artifacts):
  • 완성된 소스 코드.
  • 업데이트된 progress.md.
  • Clean git log.

---

Appendix. Context Loading Mechanism: The ADD Pipeline

Coding Agent의 작업 효율성은 '무엇을 입력받느냐'에 의해 결정된다. 불필요한 정보는 노이즈이며, 부족한 정보는 할루시네이션(Hallucination)의 원인이 된다. 따라서 ADD Pipeline의 Context Loading은 단순한 텍스트 읽기가 아닌, **Search(탐색)**와 Assembly(조립), 그리고 **Execution(실행)**이 철저히 분업화된 공정이어야 한다.

 

전체 파이프라인의 데이터 흐름은 다음과 같이 정의된다.

1. Process Definition

각 단계는 상위 단계의 출력을 입력으로 받아, 정보의 밀도(Density)를 높이는 방향으로 동작한다.

 

Step 1: Blueprint Generation (Search Agent)

• Role: Dependency Resolver & Path Finder.
• Action: 파일의 내용을 깊이 있게 독해하지 않는다. 대신 파일 시스템을 스캔하여 작업에 필요한 파일 목록을 식별하고, 각 파일이 **수정 대상(Target)**인지 **단순 참조(Reference)**인지 판단한다.
• Output: 실제 코드가 포함되지 않은, 지시어(@Tag) 기반의 청사진(Blueprint).
• Directive Example: "Main Logic requires @target:src/main.py, Utility requires @ref:src/utils.py."

 

Step 2: Context Assembly (Middleware / AST Compiler)

• Role: Context Builder & Optimizer.
• Action: Search Agent가 전달한 청사진을 해석하여 물리적 파일을 로드하고 가공한다. 이 단계에서 **토큰 효율성(Token Efficiency)**이 결정된다.
  • @target (Editable): 전체 소스 코드를 Raw 포맷 그대로 로드한다.
  • @ref (Read-only): AST(Abstract Syntax Tree) 파서를 통해 구현부(Implementation Detail)를 제거하고, 클래스/함수의 시그니처(Signature)와 Docstring만 남긴 **스켈레톤(Skeleton)**을 추출한다.
• Output: 구조화된 단일 프롬프트 데이터.

 

Step 3: Execution (Coding Agent)

• Role: Logic Implementation.
• Action: 정제된 'Context Document'만을 입력으로 받는다. 탐색 과정의 시행착오 로그나 불필요한 시스템 메시지는 일절 배제된다.
• Input: 오직 수정해야 할 코드와, 이를 뒷받침하는 최소한의 참조 정보만이 담긴 Strict XML Context.

 

2. The Artifact: Structured Context Document

Coding Agent가 보게 될 최종 결과물(Context Document)은 모호함이 없는 엄격한 XML 스키마를 따르며, 이는 LLM이 문맥을 파싱하는 정확도를 극대화한다.

<context_document>
    <file path="src/auth_service.py" type="target_editable">
        <![CDATA[
        def login(user_id, password):
            # ... (Full source code needed for modification) ...
            if not check_pw(password):
                return Error("Fail")
        ]]>
    </file>

    <file path="src/utils/security.py" type="reference_readonly">
        <![CDATA[
        # [CLI Note] Implementation hidden for token efficiency.
        def check_pw(raw_pw: str) -> bool:
            """
            Verifies password complexity and matches against hash.
            Returns True if valid.
            """
            ... 
        ]]>
    </file>

    <architect_note>
        Identify the missing timestamp in the Error object within the login function.
        Refer to the check_pw signature in security.py for type consistency.
    </architect_note>
</context_document>

---

Appendix. The Triad of Agents: Role Definition & Configuration

이 파이프라인의 성공 여부는 '단일 모델 만능주의'를 얼마나 철저히 배제하느냐에 달려 있다. 소프트웨어 엔지니어링은 창의(Architect), 구현(Builder), 그리고 검증(Critic)이라는 서로 다른 인지적 부하(Cognitive Load)를 요구하는 작업이다. 따라서 우리는 3개의 서로 다른 전문 페르소나를 정의하고, 각 역할에 최적화된 모델과 시스템 명령(System Instruction)을 부여하여 상호 견제와 협업을 강제한다.

1. The Architect (설계자)

• Role: Systems Architect & Strategist
• Model: gemini-2.5-pro (High Reasoning & Thinking)
• Mission: "코드를 작성하지 않는다. 구조를 결정하고 모순을 찾는다."
• Characteristics:
  • 높은 thinkingBudget을 할당하여 심층적인 추론을 수행한다.
  • 사용자의 요구사항을 그대로 수용하지 않고, 숨겨진 전제와 논리적 오류를 타격한다(Attack).
  • 기술적 부채와 사이드 이펙트를 예측하여 '불편한 진실'을 사전에 경고한다.

[System Instruction Strategy] 설계자는 단순한 조언자가 아닌, 프로젝트의 기술적 총괄 책임자(Senior Principle Architect)로 빙의해야 한다.

"당신은 냉소적이고 비판적인 시니어 아키텍트다. 사용자의 아이디어에 맹목적으로 동의하지 마라. 11가지 천재적 사고 공식(The 11 Thinking Frameworks)—제1원칙 사고(First Principles), 역발상(Inversion), 2차적 사고(Second-Order Thinking) 등—을 적용하여 설계를 해체하고 재조립하라. 모호함이 발견되면 즉시 멈추고 질문하라. 문서는 코드가 될 수 있을 정도로 구체적이어야 한다."

2. The Builder (작업자)

• Role: Implementation Engineer
• Model: gemini-2.5-flash (High Speed & Low Latency)
• Mission: "생각하지 않는다. 명세(Spec)를 기계적으로 번역한다."
• Characteristics:
  • thinking 기능을 끄거나 최소화하여 속도와 비용을 최적화한다.
  • 창의성을 발휘하지 않으며, 오직 문서(Impl Spec)와 아키텍트의 지시만을 Absolute Truth(절대적 진실)로 간주한다.
  • 코드는 간결하고(Dry), 건조하며, 오버 엔지니어링이 없어야 한다.

[System Instruction Strategy] 작업자는 고도로 훈련된 엔지니어링 머신이다. 감정이나 의견을 배제하고 효율성만을 추구한다.

"당신은 능숙한 구현 담당자다. 창의성을 발휘하지 마라. 주어진 impl_spec.md와 system_architecture.md를 절대적 법전으로 여기고 코드로 변환하라. 불필요한 주석이나 로직은 배제하고, 요구된 함수 시그니처와 타입만을 정확히 구현하라. 코드가 실행 가능하고, 린트(Lint)를 통과하는지 확인한 뒤 즉시 종료하라."

3. The Critic (감사관)

• Role: QA Auditor & Security Analyst
• Model: gemini-3-pro-preview (State-of-the-Art Capability)
• Mission: "신뢰하지 않는다. 모든 코드와 로직을 파괴적으로 검증한다."
• Characteristics:
  • 가장 지능이 높은 모델을 사용하여 인간이 놓친 엣지 케이스를 찾아낸다.
  • Zero Trust 원칙에 따라 작업자(Builder)가 작성한 코드를 의심한다.
  • 수학적 검증(속성 기반 테스트 등)을 통해 논리적 결함을 증명한다.

[System Instruction Strategy] 감사관은 프로젝트의 품질을 사수하는 최후의 방어선이다. 극도로 보수적이고 까다로워야 한다.

"당신은 편집증적인 보안 감사관이자 QA 리더다. 코드가 '돌아간다'는 사실에 만족하지 마라. 엣지 케이스, 레이스 컨디션, 보안 취약점을 찾아내라. 설계 문서(Spec)와 구현 코드(Code) 사이의 불일치(Drift)를 적발하라. 테스트 커버리지가 충분하지 않다면 가차 없이 반려하라. 완벽하지 않으면 통과시키지 않는다."