SKILL

기존 계획서의 특정 차수에 내용을 보충·추가한다 (서브섹션 A/B/C… 방식).

STEP 1 — 파일 및 대상 차수 특정

pwd로 현재 프로젝트 루트 확인
{프로젝트루트}/ai_history/work-plan/ 폴더 내 *.md 파일 목록 조회
-issue.md로 끝나는 파일은 제외
사용자 메시지에서 대상 파일(인덱스 번호 또는 파일명)과 대상 차수를 파악
- 예: “01번 계획서 2차에 추가” → 01.*.md 파일의 2차 수정 섹션
- 예: “1차 작업에 내용 추가” → 해당 파일의 1차 작업 섹션
- 파일이 특정되지 않으면 인덱스 번호가 가장 큰 파일 선택
- 차수가 특정되지 않으면 가장 최신 차수 선택
선택된 파일명과 대상 차수를 사용자에게 알리고 진행 의사 확인
계획서를 Read로 읽어 대상 차수의 “계획” 또는 “수정 계획” 섹션 내용 파악
기존 내용에 이미 #### A. ~ #### Z. 서브섹션이 있는지 확인
- 서브섹션 없음 → 기존 내용을 A. 원본 계획으로 감싸고, 새 내용을 B. 추가 계획으로 추가 (템플릿 E 사용)
- 서브섹션 있음 → 마지막 알파벳 다음 문자로 새 서브섹션 추가 (템플릿 F 사용)

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

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

에이전트	사용 상황
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 파일 포함): 아래 두 가지 접근을 모두 분석한다.

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

두 방식 모두 추가 계획에 구분해서 기록한다. 사용자가 제약 해제를 원하면 명시적으로 요청해야 한다고 안내한다.

추가 아키텍처 제약 — 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 3 — 내용 보충 및 저장

date 명령으로 오늘 날짜를 확인한 뒤, 아래 템플릿 중 해당하는 것으로 작성한다. Edit으로 대상 차수의 “계획”/“수정 계획” 섹션을 서브섹션 구조로 변환한다.

템플릿 E — 첫 보충 (서브섹션이 아직 없는 경우)

대상 차수의 “계획” 또는 “수정 계획” 항목의 내용을 Edit으로 서브섹션 구조로 변환한다. 기존 내용 전체를 A. 원본 계획으로 감싸고, 새 내용을 B. 추가 계획으로 추가한다.

변환 전 (예시):

- **수정 계획**:
  - MapView.tsx > toggleLayer — 수정: 레이어 토글 로직 변경
  - 예상 결과: 레이어 on/off 동작

변환 후 (예시):

- **수정 계획**:
 
  #### A. 원본 계획
  - MapView.tsx > toggleLayer — 수정: 레이어 토글 로직 변경
  - 예상 결과: 레이어 on/off 동작
 
  #### B. 추가 계획 (YYYY-MM-DD)
  - **추가 프롬프트**: {사용자 추가 요청 원문 — 한 글자도 수정하지 않고 그대로}
  - {파일명} > {함수명} — {신규/수정/삭제}: 한 줄 설명
  - 예상 결과: 한 줄

주의: - **계획**: 또는 - **수정 계획**: 라인 자체는 유지하고, 그 아래 내용만 서브섹션으로 재구성한다. 기존 내용의 들여쓰기와 형식은 그대로 보존한다.

템플릿 F — 후속 보충 (이미 A/B 등 서브섹션이 있는 경우)

대상 차수의 마지막 서브섹션 뒤에 Edit으로 다음 알파벳 서브섹션을 추가한다. (B 다음은 C, C 다음은 D, …)

마지막 서브섹션의 끝 위치를 찾아 그 아래에 추가한다. 마지막 서브섹션의 끝은 다음 중 하나로 판단한다:

다음 #### 헤딩이 나오기 직전
- **영향 범위**: 라인 직전
파일 끝

  #### {다음 알파벳}. 추가 계획 (YYYY-MM-DD)
  - **추가 프롬프트**: {사용자 추가 요청 원문 — 한 글자도 수정하지 않고 그대로}
  - {파일명} > {함수명} — {신규/수정/삭제}: 한 줄 설명
  - 예상 결과: 한 줄

STEP 4 — 완료 보고

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

업데이트된 파일 전체 경로
대상 차수 번호와 추가된 서브섹션 알파벳 (예: “2차 수정 → C. 추가 계획”)
추가 내용 핵심 요약 (3~5줄)
영향 범위 요약 — 회귀 위험이 있으면 강조 표시
#8 제약이 걸린 경우: 제약 내 방식과 제약 해제 시 방식의 차이를 한 줄씩 요약하고, “제약 해제 구현을 원하시면 명시적으로 말씀해 주세요.”를 추가
“구현을 진행하려면 말씀해 주세요.”

⛔ 중요 — 스킬 종료 규칙

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

JW's AI_Stash

Explorer