SKILL

신규 작업 계획서를 생성한다.

STEP 1 — 파일 특정

pwd로 현재 프로젝트 루트 확인
저장 폴더 = {프로젝트루트}/ai_history/work-plan/
--path {경로} 인수가 있으면 해당 경로를 저장 폴더로 사용
저장 폴더가 없으면 mkdir -p로 생성

인덱스 결정

저장 폴더 내 숫자.*.md 패턴 파일 목록 확인
가장 큰 숫자 + 1 → 다음 인덱스 (파일이 없으면 01)
항상 2자리 zero-padding (01, 02, 09, 10, 11 …)

kebab-case 이름

작업의 핵심 기능을 영문 kebab-case 3~5단어로 표현
예: map-layer-toggle, upload-progress-ui, drone-image-delete

최종 파일명: {인덱스}.{kebab-case}.md

참고 — 사용 가능한 에이전트 목록

계획서의 에이전트 사용 계획 섹션 작성 시 아래 목록을 참고해 적합한 에이전트를 선택한다.

에이전트	사용 상황
Explore	코드베이스 전체 탐색, 파일 패턴·키워드 검색, 영향 범위 파악
Plan	구현 전략·아키텍처 설계, 트레이드오프 분석이 필요할 때
gemini-researcher	외부 웹 검색, 최신 기술 동향, 라이브러리 API 정보 조사
task-review-auditor	구현 완료 후 코드 품질·정확성·버그 검증
general-purpose	위 외의 복합적 멀티스텝 조사·분석 (prompt로 역할 지정)

STEP 2 — 관련 코드 탐색

작업 대상 파일·함수·영향 범위를 파악하기 위해 코드를 탐색한다. 파악해야 할 범위가 넓으면 위 에이전트 목록을 참고해 적합한 에이전트를 활용한다.

STEP 2-3 — 유사 패턴 전수 탐색

사용자가 특정 인스턴스 하나만 언급했더라도, 코드베이스 전체에 동일한 패턴이 여러 곳에 존재하는지 반드시 확인한다.

탐색 대상:

수정 예정 컴포넌트명·함수명·CSS 클래스명·UI 텍스트를 Grep으로 전체 탐색
같은 역할을 하는 유사 컴포넌트 (예: 편집 버튼이 여러 목록에 각각 존재하는 경우)
동일 로직이 복사·붙여넣기된 코드 블록

탐색 결과 처리:

1곳만 존재: 사용자 언급 대상만 수정
여러 곳 존재: 계획서 “계획” 항목에 모든 위치를 명시하고, 모든 곳을 일괄 수정하도록 범위를 확장한다. 단, 사용자가 특정 위치만 수정하도록 명시한 경우는 예외로 하되 계획서에 나머지 위치를 참고로 기록한다.

탐색 범위가 광범위하거나 컴포넌트 구조 파악이 필요하면 Explore 에이전트를 활용한다.

STEP 2-5 — #8 제약 검토

탐색한 코드를 바탕으로 작업 범위가 api/src/core/ 또는 api/src/modules/ (hmCesium API)에 걸치는지 확인한다.

제약 없음 (Surveyor 전용 파일만 수정): STEP 2-7로 바로 진행한다.

#8 제약 해당 (hmCesium API 파일 포함): 아래 두 가지 접근을 모두 분석한다.

제약 내 방식: 기존 코드를 수정/삭제하지 않고 새 메서드·새 분기만 추가해 목표를 달성하는 방법
제약 해제 시 방식: 기존 코드를 자유롭게 수정할 수 있다면 더 나은 구현이 가능한지, 가능하다면 무엇이 달라지는지

두 방식 모두 계획서 “계획” 섹션에 구분해서 기록한다 (STEP 3 템플릿 참고). 사용자가 제약 해제를 원하면 명시적으로 요청해야 한다고 안내한다.

추가 아키텍처 제약 — core/modules 의존성 방향

api/src/core/ 또는 api/src/modules/ 파일이 포함된 경우, 제약 내 방식이든 제약 해제 방식이든 관계없이 아래 규칙을 반드시 준수한다.

✅ 허용:  modules/ → core/   (modules가 core 유틸을 사용)
❌ 금지:  core/    → modules/ (core 유틸이 modules 상태를 직접·간접 참조)

계획서 작성 시 core/에 추가하는 코드가 modules/의 상태·인스턴스·함수를 참조하는지 반드시 확인한다. 간접 참조(콜백, 전역 변수, 이벤트 등을 통한 우회 포함)도 위반으로 간주한다. 위반이 발생하는 경우 계획에 명시하고, modules/에 구현하거나 콜백 주입 방식으로 의존성을 역전시키는 대안을 제시한다.

STEP 2-7 — 영향 범위 분석

STEP 2에서 파악한 수정 예정 파일·함수를 바탕으로 Grep/Glob으로 아래를 탐색한다.

모듈 의존성: 수정 예정 파일을 import 또는 require하는 다른 파일
함수 호출부: 수정 예정 함수명을 호출하는 위치 (파일명:라인)
사이드 이펙트: DB 스키마 변경, 전역 상태 변경, 이벤트 발생 등

탐색 결과를 아래 세 항목으로 정리한다.

영향받는 모듈 목록 (없으면 “없음”)
주요 호출부 (없으면 “없음”)
회귀 위험 지점 (없으면 “없음”)

탐색 범위가 광범위하거나 파악이 어려우면 Explore 에이전트를 활용한다.

STEP 2-9 — 모듈 명세서 자동 생성 (code-spec 연동)

STEP 2 ~ STEP 2-7에서 파악한 수정 예정 파일들을 바탕으로, 영향받는 핵심 모듈을 식별하고 각 모듈의 기능명세서를 자동 생성한다.

2-9-1. 핵심 모듈 식별

수정 예정 파일 목록에서 아래 기준으로 명세서가 필요한 모듈을 판단한다.

명세서 생성 대상:

수정할 함수가 3개 이상인 파일/모듈
다른 파일에서 5회 이상 import되는 모듈
사용자가 요청한 작업의 핵심 로직을 담당하는 모듈
복잡한 의존 관계를 가진 모듈 (하위+상위 의존성 합계 5개 이상)

명세서 생성 불필요:

설정 파일, 상수 파일, 타입 정의만 있는 파일
단순 래퍼/프록시 파일 (함수 1~2개, 로직 없음)
이미 ai_history/code-spec/에 최신 명세서가 존재하는 모듈 (대상 모듈 파일의 최종 수정일 < 명세서 생성일이면 최신으로 간주)

2-9-2. 명세서 생성

식별된 각 모듈에 대해 code-spec 스킬의 STEP 2~3 절차를 실행한다.

저장 위치: {프로젝트루트}/ai_history/code-spec/
파일명: {kebab-case-모듈명}.md
여러 모듈이 대상이면 Explore 에이전트를 병렬로 활용해 분석 속도를 높인다
이미 최신 명세서가 존재하면 건너뛴다

2-9-3. 계획서에 명세서 참조 추가

생성된 명세서의 경로를 계획서 템플릿의 모듈 명세서 항목에 기록한다. 명세서의 “수정 가이드” 섹션을 참고해 계획의 수정 방향을 보강한다.

명세서 생성 대상 모듈이 없으면 (단순 수정, 소규모 변경 등) 이 스텝을 건너뛰고 계획서의 모듈 명세서 항목에 “해당 없음 (소규모 변경)“으로 기재한다.

STEP 3 — 계획서 작성 및 저장

date 명령으로 오늘 날짜를 확인한 뒤, 아래 템플릿 중 해당하는 것으로 작성한다. Write로 신규 파일 생성한다.

템플릿 A — #8 제약 없음

- **작업날짜**: YYYY-MM-DD
- **작업자**: Claude Code (claude-sonnet-4-6)
 
### 1차 작업
 
- **프롬프트**: {사용자 요청 원문 — 한 글자도 수정하지 않고 그대로 기록}
- **계획**: (각 항목은 "어디에 무엇을" 수준으로 간결하게 작성. 실제 코드는 쓰지 않는다.
  비직관적 로직·특수 순서 등 오해 소지가 있는 케이스만 추가 설명을 기재한다.
  동일 패턴이 여러 곳에 존재하면 모든 위치를 항목으로 나열한다.)
  - {파일명} > {함수명} — {신규/수정/삭제}: 한 줄 설명
  - {파일명} > {함수명} — {신규/수정/삭제}: 한 줄 설명
  - 예상 결과: 한 줄
- **영향 범위**:
  - 영향받는 모듈: {파일명 나열, 없으면 "없음"}
  - 주요 호출부: {파일명:라인 나열, 없으면 "없음"}
  - 회귀 위험: {위험 지점 설명, 없으면 "없음"}
- **모듈 명세서**: {아래 항목 포함 / 해당 없으면 "해당 없음 (소규모 변경)"}
  - `ai_history/code-spec/{모듈명}.md` — 한 줄 요약
  - (여러 개일 경우 나열)
- **에이전트 사용 계획**: {아래 항목 포함 / 사용하지 않으면 "없음"}
  - 에이전트 이름
  - 사용 목적
  - 사용 시점 (계획 수립 전 / 구현 중 / 결과 검증 시)
- **작업 내용**: 계획 수립 완료
- **결과**: 계획 수립 완료

템플릿 B — #8 제약 있음

- **작업날짜**: YYYY-MM-DD
- **작업자**: Claude Code (claude-sonnet-4-6)
 
### 1차 작업
 
- **프롬프트**: {사용자 요청 원문 — 한 글자도 수정하지 않고 그대로 기록}
- **계획**:
 
  #### 공통 분석
  - 영향 범위: 수정이 필요한 hmCesium API 파일 목록 (한 줄)
 
  #### ✅ #8 제약 내 구현 (현재 적용 가능)
  (각 항목은 "어디에 무엇을" 수준으로 간결하게 작성. 실제 코드는 쓰지 않는다.)
  - {파일명} > {함수명} — {신규/수정/삭제}: 한 줄 설명
  - 한계점: 이 방식으로 달성하지 못하는 부분 (없으면 생략)
  - 예상 결과: 한 줄
 
  #### 🔓 #8 제약 해제 시 구현 (사용자 명시 허용 시에만 적용)
  - 제약 해제가 필요한 이유: 제약 내 방식 대비 무엇이 더 나아지는지 (한 줄)
  - {파일명} > {함수명} — {수정}: 기존 코드 중 바뀌는 부분과 이유
  - 예상 결과: 한 줄
  - ⚠️ 주의: hmCesium API는 new_gsim 등 다른 프로젝트와 공유. 수정 시 다른 프로젝트 영향도 검토 필요.
 
- **영향 범위**:
  - 영향받는 모듈: {파일명 나열, 없으면 "없음"}
  - 주요 호출부: {파일명:라인 나열, 없으면 "없음"}
  - 회귀 위험: {위험 지점 설명, 없으면 "없음"}
- **모듈 명세서**: {아래 항목 포함 / 해당 없으면 "해당 없음 (소규모 변경)"}
  - `ai_history/code-spec/{모듈명}.md` — 한 줄 요약
  - (여러 개일 경우 나열)
- **에이전트 사용 계획**: {아래 항목 포함 / 사용하지 않으면 "없음"}
  - 에이전트 이름
  - 사용 목적
  - 사용 시점 (계획 수립 전 / 구현 중 / 결과 검증 시)
- **작업 내용**: 계획 수립 완료
- **결과**: 계획 수립 완료

STEP 4 — 완료 보고

저장 후 사용자에게 다음을 알린다.

저장된 파일 전체 경로
계획서의 계획 섹션 핵심 요약 (3~5줄)
영향 범위 요약 — 회귀 위험이 있으면 강조 표시
#8 제약이 걸린 경우: 제약 내 방식과 제약 해제 시 방식의 차이를 한 줄씩 요약하고, “제약 해제 구현을 원하시면 명시적으로 말씀해 주세요.”를 추가
“구현을 진행하려면 말씀해 주세요.”

⛔ 중요 — 스킬 종료 규칙

STEP 4 완료 보고 후 반드시 여기서 멈춘다. 사용자가 명시적으로 “계획대로 해줘” 등 구현 지시를 내리기 전까지 코드 파일을 절대 수정하지 않는다. 계획서 파일 외에는 어떤 파일도 Edit/Write하지 않는다.

JW's AI_Stash

Explorer