Agent Improvement Requirements

Written: 2025-12-17 Purpose: Agent improvements identified during Community Feature implementation

Current Problem:

• ❌ Only analyzes without connecting to actual UI implementation
• ❌ Figma frame links not recorded in ZenHub Story

Improvement Requirements:

1-1. Record Figma Frame Links

Content to Add to Story Body:

## 🎨 Figma Design

**프레임 링크**:
- [목록 화면](https://www.figma.com/design/QkKRtr51GXgmLdKcKcBqQe/🐶-Petaround?node-id=235-11480)
- [상세 화면](https://www.figma.com/design/...)
- [작성 화면](https://www.figma.com/design/...)

Agent Behavior:

1. 피그마 URL 파싱
2. Story 문서 생성 시 "## 🎨 Figma Design" 섹션 자동 추가
3. 각 화면별 프레임 링크 매핑

1-2. Connect to Actual UI Implementation

Current Flow:

피그마 분석 → Requirements document → BDD 시나리오 → (끝)

Improved Flow:

피그마 분석 → Requirements document → BDD 시나리오 → ZenHub 생성 → UI 구현 → 검증

Additional Phases:

Phase 7: UI 구현 (NEW)
  - /cc-flutter:feature:presentation 실행
  - 피그마 스타일 반영
  - 실제 화면 구현

Phase 8: 동작 검증 (NEW)
  - build_runner 실행
  - 테스트 실행
  - 화면 동작 확인

2. ZenHub Issue Body Format Improvement#

Current Problem:

• ❌ Only provides links (cannot verify actual content)
• ❌ Shows all content even when long (reduces readability)

Current Format:

## References
- Story 문서: `<project>/.claude/docs/community/zenhub/stories/list_story.md`
- BDD Scenarios: `<project>/.claude/docs/community/bdd/community_list.feature`

Improved Format (Using Details tags):

<details>
<summary>📝 Story 상세 내용 (클릭하여 펼치기)</summary>

## Story 설명
(전체 Story 문서 내용)

</details>

<details>
<summary>✅ Acceptance Criteria (10개)</summary>

### AC1: 목록 로딩 성공

Given the app is running # 앱이 is running ...

### AC2: 당겨서 새로고침
...

</details>

<details>
<summary>🧪 BDD Test scenarios (13개)</summary>

Feature: Community List Screen (Full BDD Feature file content)

</details>

<details>
<summary>🛠️ 구현 태스크</summary>

### Backend Tasks
- [ ] Post 모델 정의
- [ ] API 구현

### Frontend Tasks
- [ ] Domain Layer
- [ ] Data Layer
- [ ] Presentation Layer

</details>

Advantages:

• ✅ All information viewable in a single Issue
• ✅ Improved readability (collapsible sections)
• ✅ View directly without clicking links
• ✅ Viewable offline

Current Problem:

• ❌ No handling logic for existing features
• ❌ Incomplete per-phase execution
• ❌ Actual UI implementation is missing
• ❌ No verification step

Improvement Requirements:

3-1. Existing Feature Detection

1. feature/{location}/{feature_name} 존재 확인
2. 존재하면:
   - 옵션 A: 업데이트 모드
   - 옵션 B: 스킵
   - 옵션 C: 덮어쓰기 (확인 필요)
3. 존재하지 않으면:
   - 전체 생성

3-2. Complete Per-Phase Execution

Phase 2: Backend (Currently OK):

• ✅ Generate Serverpod model
• ✅ Endpoint Generation
• ✅ Code generation
• ✅ Migration

Phase 3: Frontend (Needs improvement):

// 현재: 구조만 생성
/cc-flutter:feature:domain → Entity, UseCase, Repository Interface
/cc-flutter:feature:data → Repository impl, Mixin
/cc-flutter:feature:presentation → BLoC, Page (템플릿만)

// Improvement: 실제 동작하는 코드 생성
/cc-flutter:feature:domain → (동일)
/cc-flutter:feature:data → (동일)
/cc-flutter:feature:presentation →
  - BLoC 완전 구현 (Event, State, Logic)
  - Page 완전 구현 (Scaffold, AppBar, Body)
  - Widget 완전 구현 (PostCard with 모든 필드)
  - 피그마 스타일 반영

3-3. Ensure Actual UI Implementation

Steps to Add:

Step 7-1: 피그마 분석 정보 로드
  - .claude/docs/{feature}/figma_analysis.md 읽기
  - 스타일, 레이아웃 정보 추출

Step 7-2: Widget 실제 구현
  - PostCard: 모든 필드 표시
  - CategoryChip: 스타일 적용
  - SearchBar: 동작 구현

Step 7-3: Page 실제 구현
  - Scaffold 완성
  - BLoC 연결
  - 상태별 UI (Loading, Loaded, Error, Empty)

3-4. Add Verification Step

Phase 5: Verification (needs strengthening):

# 현재
melos run build
melos run test

# Improvement
melos run build --scope={feature}
melos run analyze --scope={feature}
melos run test --scope={feature}
melos run test:bdd --scope={feature}  # Run BDD tests
flutter run --target=lib/main_development.dart  # 실제 앱 실행

File: ${CLAUDE_PLUGIN_ROOT}/commands/figma/analyze.md

Additions:

• Add "Record Figma frame links in Story" to Phase 6
• Add "## 🎨 Figma Design" section to Story template
• URL parsing and mapping logic

Template:

## 🎨 Figma Design

**프레임 링크**:
- [목록 화면]({figma_url_1})
- [상세 화면]({figma_url_2})
- [작성 화면]({figma_url_3})

**디자인 분석**:
- 컬러: {colors}
- 타이포그래피: {typography}
- 스페이싱: {spacing}

ZenHub Issue Template Improvement#

File: New file needed

Issue Body Template:

# [Story] {title}

> **Story Point**: {point}
> **Sprint**: {sprint}
> **Epic**: #{epic_number}

## 🎨 Figma Design
{figma_links}

<details>
<summary>📝 Story 상세 내용 (클릭하여 펼치기)</summary>

{story_content}

</details>

<details>
<summary>✅ Acceptance Criteria ({ac_count}개)</summary>

{ac_list}

</details>

<details>
<summary>🧪 BDD Test scenarios ({scenario_count}개)</summary>

{bdd_content}

</details>

<details>
<summary>🛠️ 구현 태스크</summary>

{tasks}

</details>

---

🤖 Generated with [Claude Code](https://claude.com/claude-code)

File: ${CLAUDE_PLUGIN_ROOT}/commands/feature/create.md

Additional Phases:

## Phase 3.5: 피그마 스타일 적용 (NEW)

### Step 3.5-1: 피그마 분석 로드
- .claude/docs/{feature}/figma_analysis.md 읽기
- Design tokens 추출 (색상, 폰트, 스페이싱)

### Step 3.5-2: 스타일 적용
- Widget에 피그마 스타일 반영
- 컬러, 타이포그래피, 레이아웃 적용

## Phase 4.5: Actual behavior implementation (NEW)

### Step 4.5-1: BLoC 로직 완성
- Event handler 실제 구현
- State transition 로직

### Step 4.5-2: Widget 완전 구현
- 모든 필드 표시
- 사용자 인터랙션
- 에러 처리

### Step 4.5-3: Page 완전 구현
- Scaffold 구성
- AppBar, Body, FAB
- 네비게이션 연결

Existing Feature Handling:

## Phase 0: Check existing Feature (NEW)

### Step 0-1: 존재 여부 확인

if [ -d "feature/{location}/{feature_name}" ]; then echo "Feature already exists"

Update mode#

else

Full generation mode#

fi

### Step 0-2: 사용자 확인
- 기존 feature 존재 시:
  - 옵션 1: 업데이트 (필드 추가, UI Improvement)
  - 옵션 2: 스킵
  - 옵션 3: 재생성 (기존 백업)

Details Tag Generation Function#

function createDetailsSection(
  summary: string,
  content: string,
  icon: string = ""
): string {
  return `
<details>
<summary>${icon} ${summary}</summary>

${content}

</details>
`;
}

// Usage example
const storyDetails = createDetailsSection(
  "Story 상세 내용 (클릭하여 펼치기)",
  storyContent,
  "📝"
);

const acDetails = createDetailsSection(
  `Acceptance Criteria (${acCount}개)`,
  acContent,
  "✅"
);

Story Body Generation Logic#

const issueBody = `
# [Story] ${title}

> **Story Point**: ${point}
> **Sprint**: ${sprint}
> **Epic**: #${epicNumber}

## 🎨 Figma Design
${figmaLinks}

${storyDetails}
${acDetails}
${bddDetails}
${tasksDetails}

🤖 Generated with [Claude Code](https://claude.com/claude-code)
`;

• Add Figma link section when generating Stories
• Extract node-id from URL and map
• Record frame links per Screen

ZenHub Issue#

• Write Details tag template
• Story Full content included
• Acceptance Criteria Full content included
• BDD Scenario Full content included
• Implementation task checklist included

• Existing feature detection logic
• Phase 3.5: Apply Figma styles
• Phase 4.5: Actual behavior implementation
• Phase 5: Complete Verification (BDD included)

1. Verify agent file locations:

      # Global settings
   ls ~/.claude/commands/  # user config 진단
   
   # Project settings
   ls .claude/commands/
   

2. /cc-flutter:figma:analyze update:

   • Add Figma link recording logic
   • Update Story template

3. Create ZenHub Issue template:

   • Utilize Details tags
   • Include full content

4. /cc-flutter:feature:create enhancement:

   • Handle existing features
   • Complete UI implementation
   • Strengthen verification

5. Actual Community UI implementation:

   • Re-run with improved agents
   • Complete a working list screen

• Dart Convention: Use singular directory names (CLAUDE.md:508-513)
• BDD Rules: English Steps + Korean comments (.claude/commands/bdd/generate.md)
• Community Requirements: .claude/docs/community/requirements.md
• Figma Analysis: .claude/docs/community/figma_analysis.md

Document Version: 1.0 Last Modified: 2025-12-17