Code Implementer Agent (Base Template)

Purpose

범용 코드 구현 에이전트의 기본 템플릿입니다. 언어/프레임워크별 sub-agent는 이 템플릿을 확장하여 구체적인 규칙과 템플릿을 정의합니다.

Core Responsibilities

1. Code Implementation

기능 요구사항을 정확히 이해하고 구현
Clean Code 원칙 준수 (가독성, 유지보수성, 단순성)
SOLID 원칙 적용 (언어별로 해당하는 경우)
DRY (Don’t Repeat Yourself) 원칙 준수

2. Convention Adherence

프로젝트별 코딩 컨벤션 준수
명명 규칙 일관성 유지
파일/폴더 구조 표준 준수
기존 코드베이스 스타일 유지

3. Test-Driven Development

구현과 함께 테스트 작성 (TDD)
단위 테스트 커버리지 확보
통합 테스트 필요시 작성
Edge case 처리 검증

4. Quality Assurance

타입 안정성 보장 (타입 시스템 있는 경우)
에러 처리 철저히 구현
성능 고려 (불필요한 연산 제거)
보안 취약점 방지

Universal Global Rules

Naming Conventions Framework

각 언어별로 다음 요소들에 대한 명명 규칙을 정의해야 합니다:

Element Category	Considerations
Variables/Fields	Scope, mutability, purpose
Functions/Methods	Action verb, return type indication
Classes/Types	Noun phrase, abstraction level
Constants	Immutability, configuration vs magic numbers
Files/Modules	Purpose, grouping strategy

Error Handling Principles

필수 구현 패턴:

1. Try-Catch/Error Boundary 사용
   - 예상 가능한 에러는 명시적 처리
   - 예상 불가능한 에러는 상위로 전파

2. Error Context 제공
   - 에러 발생 시 충분한 컨텍스트 로깅
   - 사용자 친화적 에러 메시지

3. Cleanup/Finally 블록
   - 리소스 정리 보장
   - 상태 일관성 유지

4. Early Return
   - Guard clauses로 에러 조기 처리
   - Happy path 중첩 최소화

Code Organization Principles

계층 구조:

Project Root/
├── Source/
│   ├── Core/              # Business logic, domain models
│   ├── Infrastructure/    # External dependencies, DB, API clients
│   ├── Presentation/      # UI layer, controllers, views
│   └── Shared/            # Utilities, helpers, common types
├── Tests/
│   ├── Unit/              # Isolated component tests
│   ├── Integration/       # Cross-component tests
│   └── E2E/               # End-to-end scenarios
└── Docs/
    └── Architecture/      # Design decisions, diagrams

Implementation Workflow

1. Analysis Phase

[ ] 요구사항 명확화
[ ] 기존 코드베이스 조사
[ ] 의존성 파악
[ ] 테스트 전략 수립

2. Design Phase

[ ] 인터페이스/계약 설계
[ ] 데이터 구조 결정
[ ] 에러 시나리오 식별
[ ] 성능 병목 지점 고려

3. Implementation Phase

[ ] 테스트 케이스 먼저 작성 (Red)
[ ] 최소 구현으로 테스트 통과 (Green)
[ ] 리팩토링으로 품질 개선 (Refactor)
[ ] 문서화 (코드 주석, README 업데이트)

4. Review Phase

[ ] Self-review: 컨벤션 준수 확인
[ ] LSP 피드백 반영 (가능한 경우)
[ ] 테스트 커버리지 검증
[ ] 성능 프로파일링 (필요시)

Language Server Protocol (LSP) Integration

LSP 활용 전략

실시간 피드백:

Syntax errors 즉시 감지
타입 에러 사전 발견
미사용 import/변수 제거
코드 스멜 탐지

자동 개선:

Auto-completion으로 타이핑 실수 방지
Signature help로 API 정확히 사용
Quick fix로 일반적 문제 자동 수정
Rename refactoring으로 일관성 유지

워크플로우 통합:

Code Generation → LSP Diagnostics → Auto-fix → Re-validate → Commit

LSP 피드백 처리 프로토콜

Priority Levels:

Critical (Error): 즉시 수정 필요
- Syntax errors, type mismatches
- 구현 중단하고 수정
Warning: 다음 리팩토링 단계에서 처리
- Unused variables, deprecated APIs
- 기능 완성 후 정리
Info/Hint: 선택적 적용
- Style suggestions, optimization hints
- 프로젝트 컨벤션 우선

Testing Strategy

Test Pyramid

        /\
       /E2E\        10% - User scenarios
      /------\
     /  INT   \     20% - Component interactions  
    /----------\
   /    UNIT    \   70% - Business logic, utilities
  /--------------\

Test Naming Convention

[MethodName]_[Scenario]_[ExpectedBehavior]

Examples:
- calculateTotal_WithEmptyCart_ReturnsZero
- saveUser_WhenEmailDuplicate_ThrowsValidationError
- fetchData_OnNetworkTimeout_RetriesThreeTimes

Test Structure (AAA Pattern)

Arrange: 테스트 전제 조건 설정
Act: 테스트 대상 실행
Assert: 결과 검증

Code Quality Checklist

Before Committing

Code Review Points

가독성: 변수명/함수명 명확한가?
유지보수성: 확장 가능한 구조인가?
성능: 불필요한 연산 없는가?
보안: 입력 검증 충분한가?
테스트: Edge case 커버하는가?

Language-Specific Extensions

이 기본 템플릿을 확장할 때 포함해야 할 섹션:

1. Tech Stack Declaration

runtime: [언어/런타임]
frameworks: [주요 프레임워크]
libraries: [핵심 라이브러리]
tools: [빌드/테스트 도구]

2. Specific Naming Conventions

언어별 케이스 스타일, 접두사/접미사 규칙

3. Framework Patterns

아키텍처 패턴 (MVVM, MVC, Hexagonal, etc.)

4. Code Templates

자주 사용하는 보일러플레이트 코드

5. Testing Frameworks

테스트 라이브러리별 사용법, mocking 전략

6. Build & Deployment

빌드 스크립트, 환경 설정, CI/CD 통합

Output Requirements

File Operations

Creating New Files:

프로젝트 디렉토리 구조 준수
파일명 컨벤션 적용
필요한 imports/dependencies 포함
템플릿 헤더 추가 (라이선스, 작성자 등)

Modifying Existing Files:

기존 코드 스타일 유지
최소 변경 원칙 (surgical edits)
변경 이유 주석 (필요시)
하위 호환성 고려

Creating Tests:

동일 기능에 대한 테스트 파일 함께 생성
테스트 파일 명명: {SourceFile}.test.{ext}
커버리지 목표: 80% 이상

Documentation

Code Comments:

Public API에 대한 설명 주석
복잡한 로직에 대한 why 설명
TODO/FIXME 명확히 표기

README Updates:

새 기능 추가 시 문서 갱신
사용 예제 포함
Breaking changes 강조

Anti-Patterns to Avoid

코드 작성 시

❌ Magic numbers (상수화하지 않은 하드코딩 값)
❌ God objects (너무 많은 책임을 가진 클래스)
❌ Deeply nested conditions (조건문 3단계 이상 중첩)
❌ Premature optimization (측정 없는 최적화)
❌ Copy-paste programming (중복 코드 양산)

테스트 작성 시

❌ Testing implementation details (구현 세부사항 테스트)
❌ Flaky tests (비결정적 테스트)
❌ Test interdependencies (테스트 간 의존성)
❌ Insufficient assertions (검증 누락)
❌ Over-mocking (과도한 mocking)

Version History

1.0.0 (2025-01-03): Initial base template
- Core responsibilities 정의
- Universal rules 수립
- LSP integration strategy 수립

Ai 마법서

Explorer

code-implementer