name	implement
description	Use when user wants to implement tasks from a plan (PLN-XXX). Uses TDD internally (hidden from user), guides through task-by-task implementation with progress updates in user's preferred language. Triggered by "/implement" command or requests like "구현하고 싶어요" or "코드 작성해주세요".

Implement

Overview

This skill implements tasks from plan documents (PLN-XXX) using Test-Driven Development (TDD) internally while showing clean progress updates to the user.

Use this skill when:

User wants to implement a plan
User says "/implement" or "구현하고 싶어요"
User completed planning and is ready to code
User asks to implement specific tasks from a plan

Output: Working code in src/, tests in tests/, updated plan document

Workflow

Step 1: Load Context

Goal: Understand user's background and the plan to implement.

Process:

Read CLAUDE.md from project root:
```
Read: CLAUDE.md
```
Extract:
- Preferred communication language
- Work domain
- Technical background
Find plan to implement:
- If user specified: "PLN-001을 구현하고 싶어요"
- If not specified, list available plans:
```
ls docs/plans/
```
- Ask user which plan to implement

Read plan document:

Read: docs/plans/PLN-XXX-YYYY-MM-DD-name.md

Extract from plan:
- Requirements
- Scenarios
- Tasks (with acceptance criteria)
- Verification commands

Step 2: Set Up Environment

Goal: Ensure project structure and dependencies are ready.

Process:

Check project structure exists:
```
ls src/ tests/
```
If missing:
```
mkdir -p src tests
```
Check for virtual environment:
```
ls venv/
```
If not exist, remind user:
- Korean: "먼저 가상 환경을 만들어주세요: python -m venv venv 그리고 활성화: source venv/bin/activate"
- English: "Please create a virtual environment first: python -m venv venv and activate it: source venv/bin/activate"

Step 3: Choose Implementation Order

Goal: Determine which tasks to implement and in what order.

Process:

Show task list to user:

이 계획에는 3개 태스크가 있습니다:
- Task 1: Facebook API 연동 [미완료]
- Task 2: Instagram API 연동 [미완료]
- Task 3: Excel 리포트 생성 [미완료]

어떤 순서로 구현할까요?
1. 순서대로 전부 구현 (Task 1 → 2 → 3)
2. 특정 태스크만 구현

Get user's choice
Create implementation checklist with TodoWrite:
- One todo per task
- Mark as pending initially

Step 4: Implement Each Task (TDD Cycle)

Goal: Implement one task at a time using TDD (hidden from user).

For each task, repeat:

4.1. Announce Task Start

AI: Task 1 시작: Facebook API 연동
    페이스북에서 좋아요, 댓글, 공유 수를 가져오는 기능을 만들겠습니다.

Update TodoWrite: Mark task as in_progress

4.2. TDD Cycle (Internal - Hidden from User)

Read TDD guide:

Read: references/tdd-guide.md

Process (internal):

Write test first in tests/test_<module>.py
- Use pytest
- Add @pytest.mark.scnXXX marker to map to scenarios
- Cover acceptance criteria from plan
Run test → RED (should fail)
```
pytest tests/test_<module>.py -v
```
Implement minimal code in src/<module>.py
- Read common patterns:
```
Read: references/common-patterns.md
```
- Read library recommendations:
```
Read: references/library-recommendations.md
```
- Write clean, simple code
Run test → GREEN (should pass)
```
pytest tests/test_<module>.py -v
```
If test fails 3 consecutive times (same test, same error):
- Auto-trigger debug skill:
```
Skill: debug
```
- Provide debug context: error message, test code, implementation code
- Wait for debug result
- If debug fixes issue → Continue with GREEN
- If debug escalates → Inform user, wait for guidance
Refactor if needed
- Clean up code
- Add error handling
- Add logging

DO NOT show test code to user - only show implementation code when asked.

4.3. Show Progress to User

After test passes:

AI: Task 1 완료 ✅
    src/facebook_client.py를 생성했습니다.
    페이스북 API에 연결하고 engagement 데이터를 가져올 수 있습니다.

    사용 방법:
    ```python
    from src.facebook_client import FacebookClient

    client = FacebookClient(api_key="...")
    data = client.fetch_engagement(page_id="우리회사")
    print(data)  # {'likes': 100, 'comments': 20, 'shares': 5}
    ```

Update TodoWrite: Mark task as completed

4.4. Mark Task in Plan Document

python scripts/mark_task_done.py docs/plans/PLN-XXX-... 1

This checks all acceptance criteria checkboxes for Task 1.

4.5. Handle Dependencies

If task requires dependencies:

Inform user:

이 태스크는 facebook-sdk 라이브러리가 필요합니다.
설치하시겠어요? `pip install facebook-sdk`

Wait for user confirmation

Update requirements.txt:

# If requirements.txt doesn't exist, create it
# Add new dependency with version
facebook-sdk==3.1.0

Step 5: Integration and End-to-End Test

Goal: Verify all tasks work together for each scenario.

Process:

After all tasks for a scenario are complete, create main script:

# src/report_generator.py
from facebook_client import FacebookClient
from instagram_client import InstagramClient
from excel_generator import generate_excel

def main():
    # Integrate all components
    pass

if __name__ == '__main__':
    main()

Check scenario coverage (automated):
```
python scripts/check_scenario_coverage.py docs/plans/PLN-XXX-...
```
This checks:
- All scenarios in plan have tests with @pytest.mark.scnXXX
- Runs tests for each scenario
- Reports coverage and results
Output example:
```
Found 3 scenario(s): SCN-001, SCN-002, SCN-003

✓ SCN-001: Tests found (2 file(s))
   ✅ PASS (5 test(s))

✓ SCN-002: Tests found (1 file(s))
   ✅ PASS (2 test(s))

⚠️  SCN-003: No tests found

Summary:
Scenario Coverage: 2/3 (67%)
Test Results: 2/2 passing
```
If any scenario uncovered:
- Phase 1: Show warning, don't block
- Ask user: "SCN-003에 테스트가 없습니다. 지금 추가할까요, 나중에 할까요?"
- User can choose to add now or defer
Run scenario verification from plan document:
```
python src/report_generator.py
```
Check expected output:
- File created?
- Correct content?
- Matches scenario expectations?

If verification passes:

AI: SCN-001 검증 완료 ✅
    reports/engagement-2025-10-26.xlsx 파일이 생성되었습니다.
    시나리오에 정의된 대로 작동합니다!

If verification fails → Use debug skill
Update plan status to completed:
```
python scripts/update_plan_status.py docs/plans/PLN-XXX-... completed
```
This updates the plan's YAML frontmatter:
- status: completed
- verified: true
- verification_date: YYYY-MM-DD
- updated: YYYY-MM-DD

Step 6: Documentation Update

Goal: Update docs/architecture/ with how the implementation works.

Process:

Create architecture document:

Write: docs/architecture/PLN-XXX-implementation.md

Document structure:

# PLN-XXX Implementation

## Overview
[Brief description of what was built]

## Components

### src/facebook_client.py
- Purpose: Connect to Facebook API and fetch engagement data
- Key functions:
  - `fetch_engagement(page_id)`: Returns dict with likes, comments, shares

### src/excel_generator.py
- Purpose: Generate Excel report from engagement data
- Key functions:
  - `generate_excel(data, output_path)`: Creates formatted Excel file

## Dependencies
- facebook-sdk==3.1.0
- openpyxl==3.1.2

## Usage
```bash
python src/report_generator.py

How It Works

Reads API credentials from .env
Fetches data from Facebook and Instagram
Calculates total engagement
Generates Excel file with two sheets

Inform user:

구현 문서를 작성했습니다: docs/architecture/PLN-001-implementation.md
나중에 참고할 수 있도록 작동 방식을 기록했습니다.

Step 7: Git Commit

Goal: Create commit referencing the plan ID.

Process:

Show changes:
```
git status
git diff
```

Ask user if ready to commit:

변경사항을 커밋할까요?
- src/ 폴더에 새 파일 추가
- tests/ 폴더에 테스트 추가
- docs/plans/PLN-001-... 업데이트 (태스크 완료 체크)
- docs/architecture/PLN-001-implementation.md 추가

If user agrees:

git add src/ tests/ docs/
git commit -m "Implement Tasks 1-3 from PLN-001

- Add Facebook API client
- Add Instagram API client
- Add Excel report generator
- Complete SCN-001: Daily engagement report

Ref: PLN-001"

Step 8: Next Steps Guidance

Goal: Guide user on what to do next.

Process:

If all tasks complete:

모든 태스크 구현 완료! ✅

다음 단계:
1. 실제 데이터로 테스트해보세요: `python src/report_generator.py`
2. 문제가 생기면 [debug] 스킬 사용하기
3. 새 기능 추가는 새 계획(PLN-002)을 먼저 작성하세요

"/debug" 또는 "/plan"을 입력하세요.

If partial completion:

Task 1-2 완료! ✅ (Task 3 남음)

계속 구현할까요?
1. 다음 태스크 구현 (Task 3)
2. 여기서 중단하고 나중에 계속

Key Principles

TDD is Hidden from User

DO:

Write tests first (internally)
Run tests to verify (internally)
Only show code to user when tests pass

DON'T:

Show test code to user (unless they ask)
Mention pytest in regular updates
Explain testing process to user

User sees: "Task 1 완료 ✅"

User doesn't see: "Wrote test_facebook_client.py, ran pytest, all tests passed"

Progressive Implementation

One task at a time:

Complete Task 1 fully → Show user → Mark done
Then Task 2 → Show user → Mark done
Don't try to do everything at once

Why: Easier to debug, user can test incrementally

Communication in User's Language

Adapt technical depth based on user's background (from CLAUDE.md):

Non-technical: Simple explanations, avoid jargon
Semi-technical: Use library names, show code examples
Technical: Full technical details

Example (non-technical):

페이스북에 연결하는 코드를 만들었습니다.
API 키를 .env 파일에 넣으면 데이터를 가져올 수 있어요.

Example (semi-technical):

facebook-sdk 라이브러리를 사용해서 FacebookClient 클래스를 만들었습니다.
.env 파일의 FACEBOOK_API_KEY로 인증하고, fetch_engagement() 메서드로 데이터를 가져옵니다.

Use Common Patterns

Load references as needed:

Read: references/common-patterns.md

Find patterns for:

CSV/Excel file I/O
API calls
Date/time handling
Error handling
Logging

Don't reinvent - use proven patterns.

Library Selection

Load library recommendations:

Read: references/library-recommendations.md

Based on domain (from CLAUDE.md):

Marketing → requests, openpyxl, facebook-sdk, instagrapi
Finance → pandas, openpyxl, pdfplumber
Sales → requests, openpyxl
HR → requests, openpyxl, PyYAML

Prefer built-in libraries when possible.

Troubleshooting

Tests Keep Failing

Symptom: Test fails after 2-3 attempts to fix

Solution:

Review test expectations - Are they realistic?
Check implementation logic - Is there a fundamental error?
Simplify - Break into smaller functions
Ask for help - External validation might reveal issue

Inform user:

Task 1을 구현하는 중 문제가 발생했습니다.
Facebook API 인증에서 오류가 나는데, API 키가 올바른지 확인해주시겠어요?

Be specific about what's needed.

Missing Dependencies

Symptom: Import error when running code

Solution:

Identify missing library
Install: pip install <library>
Add to requirements.txt
Re-run test

Inform user:

openpyxl 라이브러리가 필요합니다.
설치할까요? `pip install openpyxl`

User Wants to See Test Code

Symptom: "테스트 코드 보여주세요"

Solution:

AI: 테스트 코드는 tests/test_facebook_client.py에 있습니다.

    [Shows test code]

    pytest로 실행할 수 있습니다: `pytest tests/ -v`

It's okay to show tests when asked - just don't show them proactively.

Task Dependencies Are Wrong

Symptom: Task 3 needs Task 1, but they're defined independently

Solution:

Identify dependency
Implement in correct order (Task 1 → Task 3)
Update plan if needed to clarify dependencies

Resources

scripts/

mark_task_done.py - Mark task as completed in plan document (checks all acceptance criteria)
update_plan_status.py - Update plan status in YAML frontmatter (pending → in_progress → completed)
check_scenario_coverage.py - Check if all scenarios have tests with pytest markers, run tests per scenario

references/

tdd-guide.md - TDD workflow (hidden from user): RED → GREEN → REFACTOR cycle, testing patterns
common-patterns.md - Ready-to-use code patterns for CSV, Excel, API, dates, logging, error handling
library-recommendations.md - Domain-specific library recommendations (marketing, finance, sales, HR, data processing)

Example Session

User: /implement

AI: [Loads CLAUDE.md and finds plans]

AI: 어떤 계획을 구현할까요?
    1. PLN-001-2025-10-26-social-media-report.md

User: PLN-001이요

AI: [Reads plan document]

    PLN-001에는 3개 태스크가 있습니다:
    - Task 1: Facebook API 연동
    - Task 2: Instagram API 연동
    - Task 3: Excel 리포트 생성

    순서대로 전부 구현할까요?

User: 네

AI: [Creates TodoWrite todos]

    좋습니다! Task 1부터 시작하겠습니다.

AI: [Internally: writes test, implements code, runs test → GREEN]

    Task 1 완료 ✅
    src/facebook_client.py를 생성했습니다.

    [Shows usage example]

AI: [Marks task done in plan]

AI: Task 2 시작: Instagram API 연동...

    [Repeats TDD cycle]

    Task 2 완료 ✅

AI: Task 3 시작: Excel 리포트 생성...

    openpyxl 라이브러리가 필요합니다.
    설치할까요? `pip install openpyxl`

User: 네

AI: [Installs, updates requirements.txt, implements Task 3]

    Task 3 완료 ✅

AI: 모든 태스크 완료! SCN-001 검증을 시작합니다...

    [Runs: python src/report_generator.py]

    ✅ reports/engagement-2025-10-26.xlsx 생성 완료!
    시나리오대로 작동합니다.

AI: [Creates architecture doc, commits]

    구현 완료! 변경사항을 커밋했습니다.

    다음 단계:
    1. 실제 데이터로 테스트: `python src/report_generator.py`
    2. 문제 발생 시: "/debug"
    3. 새 기능 추가: "/plan"

implement

Install Skill

SKILL.md

Implement

Overview

Workflow

Step 1: Load Context

Step 2: Set Up Environment

Step 3: Choose Implementation Order

Step 4: Implement Each Task (TDD Cycle)

4.1. Announce Task Start

4.2. TDD Cycle (Internal - Hidden from User)

4.3. Show Progress to User

4.4. Mark Task in Plan Document

4.5. Handle Dependencies

Step 5: Integration and End-to-End Test

Step 6: Documentation Update

How It Works

Step 7: Git Commit

Step 8: Next Steps Guidance

Key Principles

TDD is Hidden from User

Progressive Implementation

Communication in User's Language

Use Common Patterns

Library Selection

Troubleshooting

Tests Keep Failing

Missing Dependencies

User Wants to See Test Code

Task Dependencies Are Wrong

Resources

scripts/

references/

Example Session