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:
code
```
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:
  bash
  ls docs/plans/
- •Ask user which plan to implement

•

Read plan document:

code

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:
bash
```
ls src/ tests/
```
If missing:
bash
```
mkdir -p src tests
```
•
Check for virtual environment:
bash
```
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:

code

이 계획에는 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

code

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

Update TodoWrite: Mark task as in_progress

4.2. TDD Cycle (Internal - Hidden from User)

Read TDD guide:

code

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)
bash
```
pytest tests/test_<module>.py -v
```
•
Implement minimal code in src/<module>.py
- •
  Read common patterns:
  code
  Read: references/common-patterns.md
- •
  Read library recommendations:
  code
  Read: references/library-recommendations.md
- •Write clean, simple code
•
Run test → GREEN (should pass)
bash
```
pytest tests/test_<module>.py -v
```
If test fails 3 consecutive times (same test, same error):
- •
  Auto-trigger debug skill:
  code
  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:

code

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

bash

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:

code

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

•
Wait for user confirmation

•

Update requirements.txt:

code

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

python

# 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):
bash
```
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:
code
```
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:
bash
```
python src/report_generator.py
```
•
Check expected output:
- •File created?
- •Correct content?
- •Matches scenario expectations?

•

If verification passes:

code

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

•
If verification fails → Use debug skill
•
Update plan status to completed:
bash
```
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:

code

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

•

Document structure:

markdown

# 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

code

•

Inform user:

code

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

Step 7: Git Commit

Goal: Create commit referencing the plan ID.

Process:

•
Show changes:
bash
```
git status
git diff
```

•

Ask user if ready to commit:

code

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

•

If user agrees:

bash

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:

code

모든 태스크 구현 완료! ✅

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

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

•

If partial completion:

code

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):

code

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

Example (semi-technical):

code

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

Use Common Patterns

Load references as needed:

code

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:

code

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:

code

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:

code

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

User Wants to See Test Code

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

Solution:

code

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

code

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"