기존 계획서 파일에 새로운 수정 차수(N차 수정)를 추가한다.
STEP 1 — 파일 특정
pwd로 현재 프로젝트 루트 확인{프로젝트루트}/ai_history/work-plan/폴더 내*.md파일 목록 조회-issue.md로 끝나는 파일은 제외$ARGUMENTS에 파일 경로나 파일명이 주어진 경우 해당 파일 사용, 없으면 인덱스 번호가 가장 큰 파일 선택- 사용자에게 선택된 파일명을 알리고 진행 의사를 확인
- 계획서를 Read로 읽어 현재 차수 파악 → 다음 차수 번호 결정 (
N = 현재 최고 차수 + 1) - 가장 최신 차수의 “작업 내용”이 “계획 수립 완료”이면 아직 구현이 안 된 상태임을 알리고 계속 진행할지 확인
참고 — 사용 가능한 에이전트 목록
계획서의 에이전트 사용 계획 섹션 작성 시 아래 목록을 참고해 적합한 에이전트를 선택한다.
| 에이전트 | 사용 상황 |
|---|---|
| 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 3 — 수정 차수 작성 및 저장
date 명령으로 오늘 날짜를 확인한 뒤, 아래 템플릿 중 해당하는 것으로 작성한다.
Edit으로 기존 파일 끝에 추가한다.
템플릿 C — #8 제약 없음
(기존 파일 끝에 Edit으로 추가)
### {N}차 수정
- **수정 프롬프트**: {사용자의 현재 수정 요청 원문 — 한 글자도 수정하지 않고 그대로}
- **수정 계획**: (각 항목은 "어디에 무엇을" 수준으로 간결하게 작성. 실제 코드는 쓰지 않는다.
비직관적 로직·특수 순서 등 오해 소지가 있는 케이스만 추가 설명을 기재한다.
동일 패턴이 여러 곳에 존재하면 모든 위치를 항목으로 나열한다.)
- {파일명} > {함수명} — {신규/수정/삭제}: 한 줄 설명
- {파일명} > {함수명} — {신규/수정/삭제}: 한 줄 설명
- 예상 결과: 한 줄
- **영향 범위**:
- 영향받는 모듈: {파일명 나열, 없으면 "없음"}
- 주요 호출부: {파일명:라인 나열, 없으면 "없음"}
- 회귀 위험: {위험 지점 설명, 없으면 "없음"}
- **에이전트 사용 계획**: {아래 항목 포함 / 사용하지 않으면 "없음"}
- 에이전트 이름
- 사용 목적
- 사용 시점 (계획 수립 전 / 구현 중 / 결과 검증 시)
- **작업 내용**: 계획 수립 완료
- **결과**: 계획 수립 완료템플릿 D — #8 제약 있음
(기존 파일 끝에 Edit으로 추가)
### {N}차 수정
- **수정 프롬프트**: {사용자의 현재 수정 요청 원문 — 한 글자도 수정하지 않고 그대로}
- **수정 계획**:
#### 공통 분석
- 영향 범위: 수정이 필요한 hmCesium API 파일 목록 (한 줄)
#### ✅ #8 제약 내 구현 (현재 적용 가능)
- {파일명} > {함수명} — {신규/수정/삭제}: 한 줄 설명
- 한계점: 이 방식으로 달성하지 못하는 부분 (없으면 생략)
- 예상 결과: 한 줄
#### 🔓 #8 제약 해제 시 구현 (사용자 명시 허용 시에만 적용)
- 제약 해제가 필요한 이유: 한 줄
- {파일명} > {함수명} — {수정}: 기존 코드 중 바뀌는 부분과 이유
- 예상 결과: 한 줄
- ⚠️ 주의: hmCesium API는 new_gsim 등 다른 프로젝트와 공유. 수정 시 다른 프로젝트 영향도 검토 필요.
- **영향 범위**:
- 영향받는 모듈: {파일명 나열, 없으면 "없음"}
- 주요 호출부: {파일명:라인 나열, 없으면 "없음"}
- 회귀 위험: {위험 지점 설명, 없으면 "없음"}
- **에이전트 사용 계획**: {아래 항목 포함 / 사용하지 않으면 "없음"}
- 에이전트 이름
- 사용 목적
- 사용 시점 (계획 수립 전 / 구현 중 / 결과 검증 시)
- **작업 내용**: 계획 수립 완료
- **결과**: 계획 수립 완료STEP 4 — 완료 보고
저장 후 사용자에게 다음을 알린다.
- 업데이트된 파일 전체 경로
- 추가된 차수 번호 (예: “3차 수정 추가 완료”)
- 수정 계획 핵심 요약 (3~5줄)
- 영향 범위 요약 — 회귀 위험이 있으면 강조 표시
- #8 제약이 걸린 경우: 제약 내 방식과 제약 해제 시 방식의 차이를 한 줄씩 요약하고, “제약 해제 구현을 원하시면 명시적으로 말씀해 주세요.”를 추가
- “구현을 진행하려면 말씀해 주세요.”
⛔ 중요 — 스킬 종료 규칙
STEP 4 완료 보고 후 반드시 여기서 멈춘다. 사용자가 명시적으로 “계획대로 해줘” 등 구현 지시를 내리기 전까지 코드 파일을 절대 수정하지 않는다. 계획서 파일 외에는 어떤 파일도 Edit/Write하지 않는다.