lggarrison/agent-skills

로드맵 생성하기

로드맵은 다음 사람이 대화 없이도 바로 실행할 수 있는 계획입니다. 프로젝트가 무엇을 달성하려고 하는지, 어떤 순서로 진행할지, 각 작업이 완료되었는지 어떻게 알 수 있는지, 그리고 어떤 질문이 아직 열려 있는지 명시합니다. 로드맵은 설명하는 코드 옆에 있는 저장소에 위치하므로, 다른 모든 것과 마찬가지로 검토되고 버전 관리됩니다.

로드맵은 결정을 기록합니다. 결정을 내리지 않습니다. 어떤 것이 결정되지 않았으면, 로드맵은 그렇게 명시합니다.

저장소 규칙이 우선합니다

무엇을 쓰기 전에, 저장소 자체의 규칙을 먼저 확인하세요: AGENTS.md, CLAUDE.md, CONTRIBUTING.md, 문서나 위키 스키마, 그리고 기존 로드맵이 있는지 확인합니다. 이 규칙들은 로드맵이 어디에 위치해야 하는지, 어떤 메타데이터를 가져야 하는지, 이슈가 어떻게 연결되는지, 그리고 어떤 검사를 실행해야 하는지 결정합니다. 이 스킬과 충돌할 경우 저장소 규칙이 우선합니다. 기존 로드맵 형식이 있다면, 새로운 형식을 도입하지 말고 따르세요.

워크플로우

1. 요청 파악하기

사용자가 원하는 것이 다음 중 무엇인지 파악하세요. 각각 필요한 작업량이 다릅니다:

• 새 로드맵: 프로젝트, 기능, 마이그레이션, 테스트 작업 등을 위한 것.
• 업데이트: 항목 추가 또는 변경, 단계 재정렬, 결정 기록.
• 조정: 기존 로드맵을 실제 출시된 내용과 일치하도록 업데이트.
• 검토: 로드맵을 읽고, 다시 작성하지 않고, 부족한 점을 보고.

2. 묻기 전에 증거 수집하기

프로젝트가 이미 알고 있는 것을 읽으세요: 관련 코드와 테스트, 열려 있거나 최근에 닫힌 이슈, 병합되었거나 열린 PR, 기존 문서, 그리고 해당 영역의 커밋 기록을 확인하세요. 오늘 무엇이 존재하는지, 이미 진행 중인 것이 무엇인지, 그리고 이전에 시도된 것이 무엇인지 기록하세요.

이 방법으로 배울 수 있는 것은 사용자에게 묻지 마세요.

3. 판단이 필요한 사항에 대해 질문하기

로드맵은 그 뒤에 있는 결정만큼 좋습니다. 그리고 대부분의 결정은 사용자의 몫입니다. 긴 목록 하나보다는 짧은 라운드로 질문하고, 트레이드오프가 명확하지 않을 때는 왜 그 질문이 중요한지 설명하세요. 좋은 주제는 다음과 같습니다:

• 목표: 이 노력을 할 가치가 있게 만드는 결과는 무엇이며, 그것이 달성되었는지 어떻게 알 수 있나요?
• 범위: 명시적으로 제외되는 것은 무엇인가요? 변경해서는 안 되는 것은 무엇입니까(API, 데이터 형식, 동작)?
• 제약 조건: 마감일, 릴리스, 인력, 예산, 플랫폼.
• 우선순위: 이 중 절반만 출시된다면, 어느 절반인가요?
• 위험: 가장 이해가 덜 된 부분은 무엇이며, 먼저 처리해야 합니까?
• 완료: 어떤 테스트, 지표, 또는 검토가 완료의 증거로 간주되나요?

증거가 뒷받침된다면 권장 사항을 제시하세요. 항상 사용자가 "아직 결정되지 않음"이라고 답할 수 있게 하세요. 그 답변은 추측이 아니라 미해결 결정에 들어갑니다.

작은 업데이트의 경우 바로 작성 단계로 넘어가세요. 새 로드맵의 경우 두세 번의 라운드를 예상하세요.

4. 형태 선택하기

• 하나의 파일 (ROADMAP.md 또는 저장소에 맞는 이름): 대부분의 로드맵에 적합합니다.
• 디렉토리 (roadmaps/<slug>/README.md 및 추가 페이지): 계획에 연구 노트, 디자인 스케치, 테스트 매트릭스 등 작업 항목을 묻어버릴 긴 지원 자료가 필요한 경우에만 사용하세요. 메인 페이지는 여전히 모든 작업 항목 ID를 소유합니다.

5. 작성하기

아래 템플릿을 사용하세요. 시간이 지나도 유용하게 유지하는 규칙:

• 안정적인 ID. 모든 작업 항목에 R-001과 같은 ID를 부여하세요. 번호를 다시 매기지 말고, ID를 재사용하지 마세요. 중단된 작업은 파일에 남겨두고, dropped로 표시하고 이유를 적으세요.
• 단계에는 종료 기준이 있습니다. 각 단계는 완료되었을 때 참이 되는 것을 명시합니다. 단계를 먼저 의존성 순으로, 그 다음 위험 순, 그 다음 가치 순으로 정렬하세요.
• 승인 기준은 확인 가능해야 합니다. 누군가 검증할 수 있는 기준을 작성하세요: 통과하는 테스트, 성공하는 명령어, 측정 가능한 숫자. "견고한", "개선된", "깨끗한"과 같은 단어는 피하세요.
• 의존성은 명시적으로 작성하세요. ID로 나열하세요. 다른 저장소, 벤더, 결정 등 팀의 통제를 벗어난 것은 반드시 언급하세요.
• 증거는 전체 URL 또는 저장소 상대 경로로 연결하세요. 그래야 다른 곳에 복사되어도 링크가 유지됩니다.
• 회의가 아니라 계획을 설명하세요. 현재 시제, 현재 상태를 사용하세요. 역사는 변경 로그에 들어갑니다.

6. 확인하기

전달하기 전에:

• 모든 항목에 ID, 상태, 그리고 최소 하나의 승인 기준이 있습니다.
• 모든 의존성은 존재하는 ID를 가리킵니다.
• 어떤 단계도 이후 단계에 의존하지 않습니다.
• 결정되지 않은 모든 질문은 미해결 결정 아래에 있으며, 항목 안에 숨겨져 있지 않습니다.
• 링크가 작동하고, 파일 경로가 존재합니다.
• 저장소의 형식 및 문서 검사를 통과합니다.
• 변경 로그에 이 변경 사항에 대한 항목이 있습니다.

7. 보고하기

사용자에게 생성하거나 변경한 내용, 기록한 결정, 그리고 여전히 열려 있는 질문을 알려주세요.

로드맵을 현실과 조정하기

작업이 출시되면서 로드맵은 어긋납니다. 조정하려면:

1. done 또는 dropped가 아닌 항목을 나열하세요.
2. 각 항목에 대해 병합된 PR, 닫힌 이슈, 그리고 승인 기준을 충족하는 코드를 찾으세요.
3. 모든 기준이 충족된 경우에만 항목을 done으로 표시하세요. 증거를 연결하세요.
4. 작업이 계획과 다르게 출시되었다면, 실제로 일어난 일을 반영하도록 항목을 업데이트하고 변경 로그에 차이점을 기록하세요.
5. 발견한 새 작업은 새 ID를 가진 새 항목으로 추가하세요.
6. 사용자에게 변경 사항을 요약하세요. 무엇이든 삭제하기 전에 물어보세요.

로드맵 검토하기

검토만 요청받은 경우, 다시 작성하지 마세요. 가장 중요한 것부터 보고하세요:

• 완료 시점을 알 수 없는 목표 또는 단계;
• 모호한 승인 기준이 있는 항목;
• 누락되었거나 순환하는 의존성;
• 증거가 뒷받침하지 않는데 결정된 것으로 제시된 사항;
• 코드나 이슈 추적기가 이미 완료되었거나 더 이상 관련이 없다고 보여주는 항목;
• 누락된 위험: 가장 어렵거나 이해가 덜 된 부분이 늦게 일정에 잡힌 경우.

템플릿

# <프로젝트 또는 기능> 로드맵

**목표:** <한두 문장으로 된 결과>
**상태:** <초안 | 활성 | 완료 | 대체됨>
**마지막 업데이트:** <YYYY-MM-DD>

## 컨텍스트

이 작업이 지금 중요한 이유, 오늘 존재하는 것, 그리고 증거 링크.

## 범위

- **포함:** …
- **제외:** …
- **변경 불가:** …

## 상태 범례

| 상태            | 의미                                             |
| --------------- | ------------------------------------------------ |
| `planned`       | 합의됨, 시작되지 않음                            |
| `in-progress`   | 누군가 작업 중임                                 |
| `blocked`       | 의존성 또는 결정 대기 중 (어떤 것인지 명시)     |
| `done`          | 모든 승인 기준 충족, 증거 있음                   |
| `dropped`       | 하지 않기로 함 (이유 명시)                        |

## 1단계: <이름>

**종료 기준:** <이 단계가 완료되었을 때 참인 것>

### R-001: <짧은 제목>

- **상태:** planned
- **이유:** <이것이 해결하는 문제>
- **승인 기준:**
  - [ ] <확인 가능한 진술>
- **의존성:** <ID, 또는 "없음">
- **증거:** <이슈, PR, 또는 파일 링크>

## 2단계: <이름>

…

## 미해결 결정

| ID    | 질문 | 옵션 | 차단 | 담당자 |
| ----- | ---- | ---- | ---- | ------ |
| D-001 | …    | …    | R-004 | …      |

## 위험

| 위험 | 가능성 | 영향 | 완화 방안 |
| ---- | ------ | ---- | --------- |

## 변경 로그

- <YYYY-MM-DD>: <무엇이 변경되었고 왜>

해당되지 않는 섹션은 제거하세요. 작은 로드맵은 단순히 목표, 한 단계, 그리고 변경 로그만 있을 수 있습니다.

하지 말 것

• 로드맵이 불완전해 보인다고 결정을 지어내지 마세요.
• 특정 결과가 없는 일반적인 항목("문서 추가", "테스트 개선")으로 계획을 채우지 마세요.
• 항목 번호를 다시 매기거나, 중단된 항목을 삭제하지 마세요.
• 기준을 확인하지 않고 PR 제목만 보고 작업을 done으로 표시하지 마세요.
• 로드맵 전체 내용을 이슈에 복사하거나, 그 반대를 하지 마세요. 대신 링크하세요.