AI 개발 패턴
Tests
License: MIT
Documentation
Patterns
Quality Gate
Hyperlinks
📋 귀하의 팀은 AI 지원 개발을 위해 얼마나 준비되었습니까? 무료 AI 개발 준비도 점수표 (AI Development Readiness Scorecard)를 받아 확인하고, 어떤 패턴부터 채택해야 할지 알아보세요.
이 컬렉션은 저의 경험을 바탕으로 AI 지원 소프트웨어 구축에 사용되는 패턴들을 포괄적으로 모았으며, 구현 성숙도와 개발 수명 주기 단계별로 정리되어 있습니다. 이 패턴들은 해당 분야가 발전함에 따라 변경될 수 있습니다.
용어 정의 (Terminology)
이 카탈로그는 코드 생성 및 실행, 검사 수행, 결과 반복(iterate)이 가능한 Claude Code, OpenAI Codex, Google Antigravity와 같은 도구에 대해 **코딩 에이전트 (coding agent)**라는 용어를 사용합니다. **에이전틱 엔지니어링 (Agentic engineering)**은 그러한 에이전트를 사용하여 소프트웨어를 구축하는 전문적인 실무를 의미합니다. 더 광범위한 용어인 **AI 어시스턴트 (AI assistant)**와 **AI 코딩 어시스턴트 (AI coding assistant)**는 변경 사항을 독립적으로 실행하고 검증하지 않고 제안이나 채팅을 제공할 수 있는 시스템에 사용됩니다.
채택 판정(Adoption verdicts)은 구조화되고 계층화된 증거로부터 기계적으로 재계산됩니다. 모델 기반 증거 연구는 명시적인 계획 승인이 있는 로그인된 대화형 평가자 세션에서만 온디맨드(on demand)로 실행되며, 이는 오늘날 로컬 Codex 앱에 의해 구현되었습니다. GitHub Actions는 절대 평가자 모델을 호출하거나 평가자 API 키를 받지 않습니다. CI(Continuous Integration)는 주간 읽기 전용 신선도 검사(weekly read-only freshness check)를 포함하여 결정론적 스키마(deterministic schema), 출처(provenance), 파생(derivation), 상태 드리프트(status-drift), 링크, 콘텐츠 검사를 수행합니다. 모든 안정적 및 탐색적 패턴의 평가됨(assessed), 보류 중(pending), 출처 상태는 [verification/STATUS.md]를 참조하고, 로컬 에이전트 워크플로우와 신뢰 모델은 [verification/README.md]를 참조하십시오.
graph TB
subgraph F[Foundation]
RDY[Agent Readiness] --> CR[Codified Rules] --> SS[Security Sandbox]
...
범례: 🟢 기초(Foundation) | 🟡 개발(Development) | 🔴 운영(Operations)
패턴 구성 (Pattern Organization)
이 저장소는 세 가지 패턴 카테고리를 통해 AI 지원 개발을 위한 구조화된 접근 방식을 제공합니다:
- [기초 패턴 (Foundation Patterns)]: 팀 준비 및 기본 AI 통합에 필수적인 패턴
- [개발 패턴 (Development Patterns)]: AI 지원 코딩 워크플로우를 위한 일상 실습 패턴
- [운영 패턴 (Operations Patterns)]: AI를 활용한 CI/CD, 보안 및 프로덕션 관리
- 실험적 패턴 (Experimental Patterns): 활발하게 개발되거나 고려 중인 고급 및 실험적 패턴
<a id="security-orchestration"></a>
<a id="autonomous-remediation"></a>
하네스 엔지니어링 렌즈 (Harness Engineering Lens)
하네스 엔지니어링(Harness Engineering) 프레임워크 — 에이전트 = 모델 + 하네스 —는 코딩 에이전트 주변에 구축되는 제어 장치(모델과는 별개)를 설명하며, 이를 통해 에이전트의 출력을 신뢰할 수 있게 만듭니다. 하네스 엔지니어링은 이 카탈로그의 패턴 중 하나가 아니라, 일종의 렌즈입니다. 즉, 아래에 나열된 패턴들을 그룹화하고 왜 이 패턴들을 함께 사용해야 하는지를 이해하는 방식입니다. 모든 제어 장치는 두 가지 종류 중 하나이며, 두 가지 방식으로 실행됩니다:
- 피드포워드 (Feedforward, 가이드): 에이전트가 행동하기 전에 방향을 제시합니다.
- 피드백 (Feedback, 센서): 에이전트가 행동한 후에 관찰하여 자체적으로 수정할 수 있게 합니다.
- 계산적 (Computational) 제어: 결정론적(deterministic)이고 빠르며 신뢰성이 높습니다. 예: 린터(linters), 타입 체크, 테스트, 적합도 함수(fitness functions).
- 추론적 (Inferential) 제어: 의미론적(semantic)이며 느리고 확률적입니다. 예: AI 리뷰, LLM-as-judge.
건강한 하네스는 이 네 가지 요소를 모두 균형 있게 갖춥니다. 피드포워드만 사용하는 에이전트는 규칙이 제대로 작동했는지 결코 학습하지 못하며, 피드백만 사용하는 에이전트는 같은 실수를 반복합니다. 카탈로그는 다음과 같이 렌즈에 매핑됩니다.
출처에서 직접 언급할 가치가 있는 두 가지 원칙이 있습니다:
- 품질을 초기 단계에 유지하라 (Keep Quality Left): 저렴하고 빠른 제어 장치(린터, 커밋 전 기본 검토 등)를 초기에 실행하고, 비용이 많이 드는 것들(뮤테이션 테스트, 심층 AI 리뷰 등)은 나중으로 남겨두어 문제가 가장 적은 비용으로 포착되도록 합니다.
- 자동화하지 말고 조종하라 (Steer, don't automate): 에이전트가 실수를 반복할 때, 단순히 프롬프트(prompt)만 개선하는 것이 아니라 하네스(가이드와 센서)를 개선해야 합니다. 인간의 역할은 이 하네스를 반복적으로 개선하는 것입니다.
출처: Birgitta Böckeler, "Harness Engineering", martinfowler.com.
루프 엔지니어링 렌즈
이 카탈로그의 대부분은 단일 AI 작업을 작업 단위로 취급합니다: 프롬프트를 작성하고, 출력을 얻고, 검토하는 것입니다. **루프 엔지니어링 렌즈(Loop Engineering Lens)**는 시야를 넓힙니다. 인간을 내부 루프에서 제거하고 에이전트가 반복하도록 허용하면 — 도구 출력을 읽고, 행동하고, 재확인하고, 반복하는 과정 — 작업 자체가 아니라 루프가 설계하고, 경계 짓고(bound), 검증해야 할 대상이 됩니다. Harness Engineering Lens와 마찬가지로, 이것은 카탈로그를 아우르는 렌즈일 뿐, 채택해야 할 패턴이 아닙니다. 두 가지는 상호 보완적입니다: Harness Engineering은 에이전트를 둘러싼 제어 장치가 얼마나 좋은지 (가이드 및 센서의 품질)를 묻고; Loop Engineering은 그 제어 품질이 어느 정도의 *자율성(autonomy)*을 가져다주는지, 그리고 인간이 각 반복 과정을 검사하지 않을 때 폭발 반경(blast radius)을 어떻게 제한할지를 묻습니다. 더 나은 검증 도달 범위(verification reach)는 더 많은 자율성을 사주지만, 약한 검증은 모델이 아무리 뛰어나도 그 한계를 제한합니다.
이 렌즈의 차원을 설정하는 세 가지 원칙이 있습니다:
- 실행 가능한 완료 확인(executable done-check)이 없으면 루프를 사용하지 않는다 — 시작하기 전에 게이트를 설정해야 합니다. 만약 "완료"가 명령어가 확인할 수 있는 상태(종료 코드 0 또는 1)가 아니거나, 실패가 저렴하게 되돌릴 수 없는 경우, 루프를 돌리는 대신 상호작용적으로 실행해야 합니다.
- 테스트가 모델을 중재한다 — 루프당 하나의 작업, 결정론적 검증, 그리고 에이전트는 절대 자신의 작업을 인증해서는 안 됩니다. 생산자(Producer) ≠ 채점자(grader): 코드를 작성하는 주체가 그것이 정확하다고 결정하는 주체여서는 안 됩니다.
- 검증 도달 범위가 자율성의 상한선을 설정한다 — 턴(turn), 지출(spend), 정지/분기 제한으로 루프를 경계짓고; 상태는 git에 보관하며; 인간이 업스트림 정책과 다운스트림 병합을 소유하도록 해야 합니다.
소스에서 직접 언급할 가치가 있는 두 가지 원칙이 있습니다:
- 작업 단위는 태스크(task)가 아니라 루프입니다 — 전체 루프를 설계하고, 경계를 설정하며, 검증해야 합니다. 단일 태스크는 그저 한 번의 반복일 뿐이며, 루프에 경계가 없는 상태에서 태스크만 최적화하는 것이 통제 불능 비용과 조용한 표류(silent drift)를 발생시키는 방식입니다.
- 리소스당 작성자는 한 명이어야 합니다 — 루프가 분산될 때, 두 에이전트가 동일한 파일을 작성하지 않도록 작업 항목 키(work-item keys)를 그룹화하기 전에 표준화해야 합니다. 병렬 루프는 개별 에이전트가 잘못 추론했기 때문이 아니라, 공유 리소스에 대한 이음매(seams)에서 상태를 손상시킵니다 (충돌).
루프의 게이팅(gating), 스코핑(scoping), 경계 설정에 대한 상세하고 도구별 필드 체크리스트는 Loop Engineering Checklist에서 확인할 수 있습니다.
출처: 자율 코딩 루프를 실행하기 위한 현장 실습과 '검증 도달 범위가 자율성 천장을 설정한다'는 아이디어를 종합한 것입니다. 운영 형태에 대한 내용은 동반된 Loop Engineering Checklist를 참조하십시오. 이는 위에서 다룬, 이 렌즈가 자율성 설정 제약 조건으로 취급하는 제어의 품질을 다루는 Harness Engineering Lens와 개념적으로 상호 보완적입니다.
라이프사이클 렌즈
이 카탈로그의 대부분은 메뉴판처럼 읽힙니다. 필요한 패턴을 골라 사용합니다. 하지만 **라이프사이클 렌즈(Lifecycle Lens)**는 문제를 정의하는 단계부터 실제 운영까지 하나의 기능 경로를 따라 패턴들을 순서대로 배열하여, 각 단계에서 어떤 패턴이 작업을 수행하며 어디에서 인계가 발생하는지 볼 수 있게 합니다. 하네스 엔지니어링 렌즈(Harness Engineering Lens)나 루프 엔지니어링 렌즈(Loop Engineering Lens)와 마찬가지로, 이것은 카탈로그 전체를 보는 '관점(lens)'이지 채택해야 할 패턴 자체는 아닙니다. 순서대로 단계를 진행하고 코드로 바로 건너뛰지 않는 실행 가능한 원칙 — 즉, 개발자 라이프사이클(Developer Lifecycle) 패턴에 담겨 있습니다. 이 렌즈는 각 단계별로 어떤 패턴이 해당 단계를 담당하는지를 보여주는 지도입니다.
위에서 아래로 읽어보면 이는 순방향 사슬(feedforward chain)입니다. 각 단계의 산출물이 다음 단계의 입력값이 됩니다. 카탈로그의 세 가지 범주(Foundation -> Development -> Operations)는 더 거친 수준(coarser grain)에서 동일한 흐름을 이루며, 이 렌즈는 이를 기능별로 확대하여 본 것입니다.
출처: 개발자 라이프사이클(Developer Lifecycle) 패턴의 9단계 워크플로우를 카탈로그 전체에 대한 매핑으로 일반화한 것입니다. 실행 가능한 엔드투엔드 구현은 examples/developer-lifecycle/를 참조하십시오.
패턴 의존성 및 구현 순서
중요: 이 단계들은 AI 개발이 처음인 팀을 위한 **학습 진행 과정(learning progression)**을 나타낼 뿐, 폭포수 방식(waterfall approach)은 아닙니다. 기존의 DevOps/보안 전문 지식을 갖춘 팀은 '지속적인 모든 것(continuous everything)' 모델을 따르며 첫날부터 모든 단계에 걸쳐 패턴들을 지속적으로 구현해야 합니다.
graph TD
subgraph "Phase 1: Foundation (Weeks 1-2)"
A[Agent Readiness] --> B[Codified Rules]
...
지속적인 구현 참고 사항: 보안 패턴(Security Sandbox, AI 보안 및 규정 준수 (AI Security & Compliance))과 배포 패턴은 특정 단계까지 지연시키는 것이 아니라 개발 전반에 걸쳐 지속적으로 구현되어야 합니다. 표시된 종속성은 배포 게이트가 아닌 학습 필수 조건을 나타냅니다.
패턴 참조 전체
| 패턴 | 성숙도 | 카테고리 | 유형 | 설명 | 종속성 |
|---|
| 기초 (Foundation) | | 기초 | | 팀 준비 상태 및 기본적인 AI 통합 인프라 | |
| ... | | | | | |
패턴 성숙도 수준
패턴은 구현 복잡성과 필수 지식에 따라 분류됩니다:
입문자 (Beginner): 최소한의 설정만으로 사용 가능한 기본 AI 도구 활용
- 필수 조건: 기본적인 프로그래밍 기술, AI 도구 접근성
- 복잡도: 단일 도구 사용, 간단한 프롬프트
- 예시: 간단한 코드 생성, 기본적인 제약 조건 설정
중급 (Intermediate): 다중 도구 조정 및 프로세스 통합
- 필수 조건: 개발 워크플로우 경험, 팀 조정 능력
- 복잡도: 여러 도구, 오케스트레이션 패턴, 품질 게이트
- 예시: 테스트 전략, 병렬 워크플로우, 선택지 생성
고급 (Advanced): 엔터프라이즈 수준의 복잡한 시스템
- 필수 조건: 아키텍처 경험, 보안/규정 준수 지식
- 복잡도: 다중 에이전트 시스템, 고급 안전성(advanced safety), 규정 준수 자동화
- 예시: 엔터프라이즈 보안, 규정 준수 자동화, 카오스 엔지니어링
작업 크기 추정 프레임워크
패턴은 목적과 맥락에 따라 다양한 작업 크기 추정 접근 방식을 사용합니다:
graph TD
A[기능 요청 (Feature Request)] --> B[이슈 생성 (Issue Generation)]
B --> C[1시간 미만 작업 항목 (Sub-1-Hour Work Items)]
...```