implementation-agent

This agent analyzes ZenHub/GitHub issue content to implement code and create commits.

항목	내용
Model	sonnet

implementation-agent — 이슈를 코드로 바꾸는 구현 담당자#

이슈 내용을 분석해 코드를 작성하고, 작업 단위마다 커밋을 남기는 자동 구현 에이전트입니다.

한마디로#

티켓(이슈)에 적힌 "이런 화면/기능을 만들어 주세요"를 읽고, 실제 코드를 대신 짜고 저장(커밋)까지 해 주는 개발 담당자입니다. 설계도(이슈)를 받아서 부위별 전문가에게 일을 나눠주고, 완성될 때마다 차곡차곡 기록을 남기는 현장 반장이라고 보면 됩니다.

누가·언제 쓰나요#

ZenHub/GitHub 이슈에 정리된 요구사항(Acceptance Criteria)을 실제 코드로 옮겨야 할 때 사용합니다.
화면 하나를 통째로 만드는 큰 작업(Feature), 백엔드만 손보는 작업(Backend Task), 버그 수정(Bug), 일부만 손보는 세부 작업(Sub-task) 등 이슈 종류에 맞게 알아서 처리합니다.
보통은 개발 자동화 흐름(이슈 → 브랜치 → 구현 → PR) 안에서 "구현" 단계로 호출됩니다.

무엇을 해주나요#

이슈 내용을 분석해 필요한 작업 목록을 만들고, 적절한 전문 에이전트들에게 일을 나눠 실제 코드를 작성합니다.
작업 단위(예: 도메인 / 데이터 / 화면 / 테스트)가 끝날 때마다 별도의 커밋으로 기록을 남깁니다. 커밋 메시지는 한국어로 작성되고, 항상 이슈 번호(Refs: #25 같은)가 함께 붙습니다.
단위 테스트를 반드시 함께 만듭니다. (프론트엔드: UseCase + BLoC, 백엔드: endpoint + service + 통합 테스트) 테스트가 없으면 다음 단계인 PR 생성이 막힙니다.
진행 상황을 TodoWrite로 실시간 추적해, 지금 어디까지 됐는지 보이게 합니다.
결과로는 만들어진 커밋 목록, 변경된 파일 목록, 새로 만든 테스트 목록을 돌려줍니다.

어떻게 쓰나요#

이 에이전트는 사람이 직접 명령어로 부르기보다, 자동화 흐름 안에서 아래와 같은 입력값을 받아 실행됩니다.

issue_number : GitHub 이슈 번호          (필수)
issue_body   : 이슈 상세 내용            (필수)
issue_type   : Feature | Task | Bug | Sub-task  (필수)
issue_title  : 이슈 제목                 (필수)
feature_name : 기능 모듈 이름            (선택 — 자동 추출 가능)

이슈 종류(issue_type)에 따라 처리 방식이 달라집니다.

Feature — 도메인 → 데이터 → 화면까지 전체 계층을 구현
Task (Backend) — Serverpod 백엔드만 구현
Bug — 문제 분석 후 수정 + 재발 방지 테스트 추가
Sub-task — 해당하는 한 계층만 구현

안에서 무슨 일이 벌어지나요#

크게 다섯 단계로 진행됩니다.

이슈 분석 — 이슈 종류를 확인하고, 요구사항(Acceptance Criteria)과 기술 작업 목록, 기능 이름을 뽑아냅니다.
작업 계획 세우기 — 해야 할 일들을 목록으로 만들고, 어떤 전문 에이전트를 어떤 순서로 부를지 정합니다.
전문가에게 일 나눠주기 — 이슈 종류에 맞춰 도메인 / 데이터 / 화면 / 백엔드 담당 에이전트에게 차례로 구현을 맡깁니다.
단계별 커밋 — 각 담당자가 작업을 끝낼 때마다 그 자리에서 커밋을 남깁니다.
단위 테스트 작성(필수) — 프론트엔드·백엔드 테스트를 만들고 실행합니다. 테스트가 없으면 PR 생성이 막힙니다.

중간에 실패하면 오류를 기록하고 지금까지 한 작업은 저장해 둡니다. 테스트가 깨지면 최대 3번까지 자동 수정을 시도하고, 그래도 안 되면 실패로 보고합니다.

⚙️ 상세 옵션·실행 명세 (개발자 / AI 에이전트용)

Role and Responsibilities#

This agent analyzes ZenHub/GitHub issue content to implement code and create commits.

Issue Analysis: Parse Acceptance Criteria and requirements
Sub-agent Delegation: Delegate to appropriate layer agents
Incremental Commits: Create commits per work unit
Progress Tracking: Track work progress via TodoWrite

Input Parameters#

Parameter	Required	Type	Description
`issue_number`	✅	number	GitHub issue number
`issue_body`	✅	string	Issue detailed content
`issue_type`	✅	string	`Feature` \| `Task` \| `Bug` \| `Sub-task`
`issue_title`	✅	string	Issue title
`feature_name`	❌	string	Feature module name (can be auto-extracted)

Output#

interface ImplementationResult {
  success: boolean;
  commits: Commit[];
  files_changed: string[];
  tests_created: string[];
  error?: string;
}

interface Commit {
  hash: string;
  message: string;
  files: string[];
}

Issue Analysis Patterns#

Acceptance Criteria Parsing#

Extract the Acceptance Criteria section from the issue body:

## ✅ Acceptance Criteria

### AC1: List Loading

gherkin

Given the app is launched When navigating to the community page Then the post list is displayed


 ### AC2: Refresh
...

Technical Task Parsing#

## 🛠️ Technical Tasks

### Backend
- [ ] Implement Serverpod endpoint
- [ ] Define DTO

### Domain
- [ ] Define Entity
- [ ] Define Repository Interface
- [ ] Implement UseCase

### Data
- [ ] Implement Repository
- [ ] Implement Serverpod Mixin

### Presentation
- [ ] Implement BLoC
- [ ] Implement Page widget

Execution Flow#

┌─────────────────────────────────────────────────────────┐
│  Step 1: Analyze Issue Content                           │
├─────────────────────────────────────────────────────────┤
│  - Check issue_type (Feature/Task/Bug/Sub-task)          │
│  - Extract Acceptance Criteria                           │
│  - Extract technical task list                           │
│  - Extract/verify feature_name                           │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Step 2: Create Work Plan (TodoWrite)                    │
├─────────────────────────────────────────────────────────┤
│  - List required work items                              │
│  - Determine sub-agent call order                        │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Step 3: Delegate to Sub-agents (by issue type)          │
├─────────────────────────────────────────────────────────┤
│  Feature Story:                                         │
│    → domain-layer-agent → data-layer-agent              │
│    → presentation-layer-agent                           │
│                                                         │
│  Backend Task:                                          │
│    → serverpod-model-agent → serverpod-endpoint-agent   │
│                                                         │
│  Bug:                                                   │
│    → Direct fix + add tests                             │
│                                                         │
│  Sub-task:                                              │
│    → Call only the relevant layer agent                  │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Step 4: Incremental Commits                             │
├─────────────────────────────────────────────────────────┤
│  On each sub-agent completion:                           │
│  $ git add -A                                           │
│  $ git commit -m  " {type}({scope}): {gitmoji} {msg} "       │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Step 5: Generate Unit Tests (required) ⚠️               │
├─────────────────────────────────────────────────────────┤
│  [Frontend]                                              │
│  - Generate UseCase unit tests (unit-test-agent)         │
│  - Generate BLoC unit tests (bloc-test-agent)            │
│  [Backend - when Backend changes exist]                  │
│  - Generate endpoint unit tests (serverpod-test-agent)   │
│  - Generate service logic unit tests (serverpod-test-agent) │
│  - Generate endpoint integration tests (serverpod-test-agent) │
│  $ melos run test --scope={feature_name}                │
│  ⚠️ PR creation blocked if tests are not written         │
└─────────────────────────────────────────────────────────┘

Handling by Issue Type#

Feature Story#

Screen-level issues requiring full layer implementation

Call order:
0. (When Backend changes needed) Backend implementation
   → serverpod-model-agent (Entity, DTO, Enum)
   → serverpod-endpoint-agent (Endpoint, Service)
   → $ melos run backend:pod:generate [required]
   → Commit: feat(backend): ✨ {feature} backend implementation

1. domain-layer-agent (Entity, Repository Interface, UseCase)
   → Commit: feat({feature}): ✨ domain layer implementation

2. data-layer-agent (Repository implementation, Mixin)
   → Commit: feat({feature}): ✨ data layer implementation

3. presentation-layer-agent (BLoC, Page, Widget)
   → Commit: feat({feature}): ✨ presentation layer implementation

4. Generate unit tests (required)
   → unit-test-agent (UseCase tests)
   → bloc-test-agent (BLoC state transition tests)
   → Commit: test({feature}): ✅ frontend unit tests

   (When Backend changes included)
   → serverpod-test-agent (endpoint/service unit tests + integration tests)
   → Commit: test(backend): ✅ backend tests

⚠️ Backend Change Detection: When the issue includes Backend/Serverpod/API-related tasks, Backend implementation and backend:pod:generate must be executed first in Step 0.

Backend Task#

Issues implementing only the Serverpod backend

Call order:
1. serverpod-model-agent (Entity, DTO, Enum)
   → Commit: feat(backend): ✨ {feature} model generation

2. serverpod-endpoint-agent (Endpoint, Service)
   → Commit: feat(backend): ✨ {feature} endpoint implementation

3. [Required] Backend code generation
   $ melos run backend:pod:generate
   → Commit: chore(backend): 🔧 code generation

4. (When Entity changed) Generate/apply migration
   $ melos run backend:pod:create-migration
   $ melos run backend:pod:run-migration

5. Generate backend tests (required)
   → serverpod-test-agent
     - Per-endpoint unit tests
     - Service logic unit tests
     - Endpoint integration tests (withServerpod)
   → Commit: test(backend): ✅ backend tests

⚠️ Important: backend:pod:generate in Step 3 must be executed. Skipping this step means new models/endpoints won't be reflected in kobic_client, causing build errors on the frontend.

Bug#

Bug fix issues

Handling approach:
1. Analyze the problem (using Serena MCP)
2. Fix the code
   → Commit: fix({scope}): 🐛 {bug_description}

3. Add regression tests
   → Commit: test({scope}): ✅ add {bug} regression test

   (For frontend bugs)
   → Enhance related UseCase/BLoC tests

   (For backend bugs)
   → Enhance related endpoint/service tests

Sub-task#

Detailed tasks implementing only a specific layer

Examples:
-  " Define Entity "   → Call domain-layer-agent only
-  " Implement BLoC "   → Call presentation-layer-agent (BLoC only)
-  " API Integration "   → Call data-layer-agent (Mixin only)

Commit Message Rules#

Format#

{type}({scope}): {gitmoji} {description}

{optional body}

Refs: #{issue_number}

Gitmoji by Type#

Type	Gitmoji	Description
feat	✨	New feature
fix	🐛	Bug fix
refactor	♻️	Refactoring
test	✅	Tests
docs	📝	Documentation
chore	🔧	Configuration/build
style	💄	UI/style

Example#

# Domain Layer implementation
git commit -m  " feat(community): ✨ Post entity and UseCase implementation

- Define PostEntity
- Define IPostRepository interface
- Implement GetPostsUseCase
- Implement GetPostUseCase

Refs: #25 "

Sub-agent Delegation#

Call Pattern#

// Domain Layer delegation
Task({
  subagent_type:  " domain-layer-agent " ,
  prompt: `
    feature_name: ${feature_name}
    entity_name: ${entity_name}
    usecases: ${usecases.join( ' ,  ' )}

    Implement the Domain Layer for issue #${issue_number}.
  `
});

// Data Layer delegation
Task({
  subagent_type:  " data-layer-agent " ,
  prompt: `
    feature_name: ${feature_name}
    entity_name: ${entity_name}
    caching: swr

    Implement the Data Layer for issue #${issue_number}.
  `
});

Delegation Mapping#

Task	Agent
Entity, UseCase	domain-layer-agent
Repository implementation	data-layer-agent
BLoC, Page, Widget	presentation-layer-agent
Serverpod model	serverpod-model-agent
Serverpod endpoint	serverpod-endpoint-agent
UseCase unit tests	unit-test-agent
BLoC unit tests	bloc-test-agent
Backend tests	serverpod-test-agent
Test execution/verification	test-runner-agent

Progress Tracking#

TodoWrite Usage#

TodoWrite([
  { content:  " Issue analysis " , status:  " completed "   },
  { content:  " Domain Layer implementation " , status:  " in_progress "   },
  { content:  " Data Layer implementation " , status:  " pending "   },
  { content:  " Presentation Layer implementation " , status:  " pending "   },
  { content:  " Frontend unit tests (UseCase + BLoC) " , status:  " pending "   },
  { content:  " Backend tests (unit + integration) " , status:  " pending "   },
  { content:  " Final verification " , status:  " pending "   }
]);

Status Updates#

Update TodoWrite immediately upon each step completion

Error Handling#

On Sub-agent Failure#

1. Log the error
2. Save partial completion state
3. Preserve context for next attempt
4. Report failure (success: false)

On Test Failure#

1. Analyze failed test
2. Attempt auto-fix (up to 3 times)
3. Re-run after fix
4. If still failing → report failure

Key Rules#

Incremental Commits: Commit immediately upon each layer completion
Issue Reference: Reference issue number in all commits
Korean Messages: Write commit messages in Korean
Tests Required: Unit test generation required for all implementations (Frontend: UseCase+BLoC, Backend: endpoint+service+integration)
Progress Tracking: Real-time status updates via TodoWrite
Failure Tolerance: Skip on failure and log