LogoSkills

implementation-agent

이 에이전트는 ZenHub/GitHub 이슈 내용을 분석해 코드를 구현하고 커밋을 생성합니다.

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

항목내용
모델sonnet

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

한마디로#

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

누가·언제 쓰나요#

  • 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 — 해당하는 한 계층만 구현

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

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

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

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

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

Role and Responsibilities#

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

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

Input Parameters#

ParameterRequiredTypeDescription
issue_number✅numberGitHub issue number
issue_body✅stringIssue detailed content
issue_type✅stringFeature | Task | Bug | Sub-task
issue_title✅stringIssue title
feature_name❌stringFeature 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
...

⚠️ ## 📄 상세 기획 아티팩트 링크는 보조 컨텍스트다 — AC 의 출처가 아니다. 이슈 본문 상단에 claude.ai 아티팩트 링크가 있어도 AC 파싱 대상은 언제나 이슈 본문이다. AC 를 찾으려고 그 링크를 WebFetch 하지 말 것 — 아티팩트는 발행 시 비공개라 헤드리스·CI 세션에서 실패한다. 배경·설계 서술이 더 필요할 때만 선택적으로 열어 본다.

본문에 AC 가 아예 없다면 그것은 "아티팩트를 열어야 한다"는 신호가 아니라 이슈가 규약을 위반한 것이다(SoT: rules/zenhub-conventions.md → Issue Body Artifact Contract). 링크를 fetch 하는 우회 대신 이슈를 고친다.

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#

TypeGitmojiDescription
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#

TaskAgent
Entity, UseCasedomain-layer-agent
Repository implementationdata-layer-agent
BLoC, Page, Widgetpresentation-layer-agent
Serverpod modelserverpod-model-agent
Serverpod endpointserverpod-endpoint-agent
UseCase unit testsunit-test-agent
BLoC unit testsbloc-test-agent
Backend testsserverpod-test-agent
Test execution/verificationtest-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#

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