Plan 모드: 실행 가능한 마크다운 계획 작성

Plan 모드

사용자가 실행이 아닌 계획을 원할 때 이 스킬을 사용하세요.

핵심 동작

이번 턴에서는 계획만 수립합니다.

• 코드를 구현하지 마세요.
• 계획 마크다운 파일 외에 프로젝트 파일을 편집하지 마세요.
• 변경을 유발하는 터미널 명령어, 커밋, 푸시 또는 외부 작업을 실행하지 마세요.
• 필요할 때 읽기 전용 명령어/도구를 사용하여 저장소나 기타 컨텍스트를 검사할 수 있습니다.
• 결과물은 활성 워크스페이스 내 .hermes/plans/ 디렉터리에 저장된 마크다운 계획입니다.

출력 요구사항

구체적이고 실행 가능한 마크다운 계획을 작성하세요.

해당하는 경우 다음을 포함합니다:

• 목표
• 현재 컨텍스트 / 가정
• 제안된 접근 방식
• 단계별 계획
• 변경될 파일
• 테스트 / 검증
• 위험, 트레이드오프, 미결 질문

작업이 코드와 관련된 경우 정확한 파일 경로, 예상 테스트 대상, 검증 단계를 포함하세요.

저장 위치

write_file을 사용하여 다음 경로에 계획을 저장하세요:

• .hermes/plans/YYYY-MM-DD_HHMMSS-<slug>.md

이 경로는 활성 작업 디렉터리 / 백엔드 워크스페이스를 기준으로 합니다. Hermes 파일 도구는 백엔드를 인식하므로, 이 상대 경로를 사용하면 로컬, 도커, SSH, Modal, Daytona 백엔드에서 계획이 워크스페이스와 함께 유지됩니다.

런타임이 특정 대상 경로를 제공하는 경우 해당 정확한 경로를 사용하세요. 제공하지 않는 경우 .hermes/plans/ 아래에 적절한 타임스탬프 파일명을 직접 생성하세요.

상호작용 스타일

• 요청이 충분히 명확하면 계획을 바로 작성하세요.
• /plan에 명시적인 지시사항이 없으면 현재 대화 컨텍스트에서 작업을 추론하세요.
• 실제로 불충분하게 명시된 경우 추측하지 말고 간단한 명확화 질문을 하세요.
• 계획을 저장한 후, 무엇을 계획했는지와 저장된 경로를 간략히 답변하세요.

---

좋은 계획 작성하기

이 스킬의 나머지 부분은 위 마크다운 파일 내부에 들어갈 좋은 구현 계획을 작성하는 기술입니다.

개요

구현자가 코드베이스에 대한 컨텍스트가 전혀 없고 의심스러운 취향을 가졌다고 가정하고 포괄적인 구현 계획을 작성하세요. 그들이 알아야 할 모든 것을 문서화하세요: 어떤 파일을 건드릴지, 완전한 코드, 테스트 명령어, 확인할 문서, 검증 방법. 작은 단위의 작업을 제공하세요. DRY. YAGNI. TDD. 빈번한 커밋.

구현자는 숙련된 개발자이지만 도구 세트나 문제 도메인에 대해 거의 아무것도 모른다고 가정하세요. 그들이 좋은 테스트 설계를 잘 알지 못한다고 가정하세요.

핵심 원칙: 좋은 계획은 구현을 명확하게 만듭니다. 누군가 추측해야 한다면 계획이 불완전한 것입니다.

전체 구현 계획이 도움이 되는 경우

다음 작업 전에는 항상 사용하세요:

• 다단계 기능 구현
• 복잡한 요구사항 분해
• 서브에이전트 기반 개발을 통한 서브에이전트 위임

다음 경우에는 건너뛰지 마세요:

• 기능이 단순해 보일 때 (가정이 버그를 만듭니다)
• 직접 구현할 계획일 때 (미래의 당신이 지침이 필요합니다)
• 혼자 작업할 때 (문서화가 중요합니다)

작은 단위의 작업 세분화

각 작업 = 2~5분의 집중 작업.

모든 단계는 하나의 행동입니다:

• "실패하는 테스트 작성" — 단계
• "실패하는지 확인하기 위해 실행" — 단계
• "테스트를 통과시키는 최소 코드 구현" — 단계
• "테스트를 실행하고 통과하는지 확인" — 단계
• "커밋" — 단계

너무 큼:

### 작업 1: 인증 시스템 구축
[5개 파일에 50줄의 코드]

적절한 크기:

### 작업 1: 이메일 필드가 있는 User 모델 생성
[1개 파일에 10줄]

### 작업 2: User에 비밀번호 해시 필드 추가
[1개 파일에 8줄]

### 작업 3: 비밀번호 해싱 유틸리티 생성
[1개 파일에 15줄]

계획 문서 구조

헤더 (필수)

모든 계획은 다음으로 시작해야 합니다:

# [기능 이름] 구현 계획

> **Hermes용:** 이 계획을 작업별로 구현하려면 subagent-driven-development 스킬을 사용하세요.

**목표:** [이것이 무엇을 구축하는지 한 문장]

**아키텍처:** [접근 방식에 대한 2~3문장]

**기술 스택:** [핵심 기술/라이브러리]

---

작업 구조

각 작업은 다음 형식을 따릅니다:

### 작업 N: [설명적인 이름]

**목표:** 이 작업이 달성하는 것 (한 문장)

**파일:**
- 생성: `exact/path/to/new_file.py`
- 수정: `exact/path/to/existing.py:45-67` (알고 있는 경우 줄 번호)
- 테스트: `tests/path/to/test_file.py`

**단계 1: 실패하는 테스트 작성**

```python
def test_specific_behavior():
    result = function(input)
    assert result == expected
```

**단계 2: 테스트를 실행하여 실패 확인**

실행: `pytest tests/path/test.py::test_specific_behavior -v`
예상: FAIL — "function not defined"

**단계 3: 최소 구현 작성**

```python
def function(input):
    return expected
```

**단계 4: 테스트를 실행하여 통과 확인**

실행: `pytest tests/path/test.py::test_specific_behavior -v`
예상: PASS

**단계 5: 커밋**

```bash
git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature"
```

작성 과정

단계 1: 요구사항 이해

다음을 읽고 이해하세요:

• 기능 요구사항
• 설계 문서 또는 사용자 설명
• 승인 기준
• 제약사항

단계 2: 코드베이스 탐색

Hermes 도구를 사용하여 프로젝트를 이해하세요:

# 프로젝트 구조 이해
search_files("*.py", target="files", path="src/")

# 유사한 기능 살펴보기
search_files("similar_pattern", path="src/", file_glob="*.py")

# 기존 테스트 확인
search_files("*.py", target="files", path="tests/")

# 주요 파일 읽기
read_file("src/app.py")

단계 3: 접근 방식 설계

다음을 결정하세요:

• 아키텍처 패턴
• 파일 구성
• 필요한 종속성
• 테스트 전략

단계 4: 작업 작성

다음 순서로 작업을 만드세요:

1. 설정/인프라
2. 핵심 기능 (각각 TDD)
3. 엣지 케이스
4. 통합
5. 정리/문서화

단계 5: 완전한 세부정보 추가

각 작업에 대해 다음을 포함하세요:

• 정확한 파일 경로 ("설정 파일"이 아닌 src/config/settings.py)
• 완전한 코드 예제 ("검증 추가"가 아닌 실제 코드)
• 예상 출력을 포함한 정확한 명령어
• 작업이 작동함을 증명하는 검증 단계

단계 6: 계획 검토

다음을 확인하세요:

• 작업이 순차적이고 논리적입니까?
• 각 작업이 작은 단위(2~5분)입니까?
• 파일 경로가 정확합니까?
• 코드 예제가 완전합니까?(복사하여 붙여넣기 가능)
• 명령어가 정확하고 예상 출력이 포함되어 있습니까?
• 누락된 컨텍스트가 없습니까?
• DRY, YAGNI, TDD 원칙이 적용되었습니까?

원칙

DRY (반복하지 마세요)

나쁨: 3곳에 검증 로직 복사-붙여넣기 좋음: 검증 함수를 추출하여 모든 곳에서 사용

YAGNI (그것은 필요하지 않을 것입니다)

나쁨: 미래 요구사항을 위한 "유연성" 추가 좋음: 지금 필요한 것만 구현

# 나쁨 — YAGNI 위반
class User:
    def __init__(self, name, email):
        self.name = name
        self.email = email
        self.preferences = {}  # 아직 필요 없음!
        self.metadata = {}     # 아직 필요 없음!

# 좋음 — YAGNI
class User:
    def __init__(self, name, email):
        self.name = name
        self.email = email

TDD (테스트 주도 개발)

코드를 생성하는 모든 작업은 전체 TDD 사이클을 포함해야 합니다:

1. 실패하는 테스트 작성
2. 실행하여 실패 확인
3. 최소 코드 작성
4. 실행하여 통과 확인

자세한 내용은 test-driven-development 스킬을 참조하세요.

빈번한 커밋

각 작업 후에 커밋하세요:

git add [files]
git commit -m "type: description"

일반적인 실수

모호한 작업

나쁨: "인증 추가" 좋음: "이메일과 password_hash 필드가 있는 User 모델 생성"

불완전한 코드

나쁨: "단계 1: 검증 함수 추가" 좋음: "단계 1: 검증 함수 추가"와 함께 완전한 함수 코드

검증 누락

나쁨: "단계 3: 작동하는지 테스트" 좋음: "단계 3: pytest tests/test_auth.py -v 실행, 예상: 3 passed"

파일 경로 누락

나쁨: "모델 파일 생성" 좋음: "생성: src/models/user.py"

실행 핸드오프

계획을 저장한 후 실행 접근 방식을 제안하세요:

"계획이 완료되어 저장되었습니다. subagent-driven-development를 사용하여 실행할 준비가 되었습니다 — 각 작업마다 새로운 서브에이전트를 할당하고 2단계 리뷰(명세 준수 확인 후 코드 품질 검토)를 수행합니다. 진행할까요?"

실행할 때는 subagent-driven-development 스킬을 사용하세요:

• 각 작업에 대해 전체 컨텍스트와 함께 새로운 delegate_task
• 각 작업 후 명세 준수 리뷰
• 명세 통과 후 코드 품질 리뷰
• 두 리뷰 모두 승인할 때만 진행

기억하세요

작은 단위의 작업 (각 2~5분)
정확한 파일 경로
완전한 코드 (복사하여 붙여넣기 가능)
예상 출력을 포함한 정확한 명령어
검증 단계
DRY, YAGNI, TDD
빈번한 커밋

좋은 계획은 구현을 명확하게 만듭니다.