코딩과 개발 보조 스킬 패턴

문제 상황: 코드를 쓰기 전에 저장소를 읽어야 한다

개발 보조 에이전트를 처음 쓰면 가장 먼저 기대하는 일은 코드 생성이다. "이 기능 만들어 줘", "이 버그 고쳐 줘"라고 요청하면 Claude Code, Codex, Gemini CLI 같은 도구가 파일을 열고 코드를 제안한다. 빠르다. 그러나 빠른 생성이 항상 안전한 변경은 아니다.

실제 개발 업무에서 더 어려운 일은 새 코드를 쓰는 것이 아니라 기존 저장소의 맥락을 이해하는 것이다. 이 함수가 어디서 호출되는지, 설정값은 어디서 주입되는지, 테스트는 어떤 전제를 갖는지, 작은 수정이 어떤 화면과 API에 영향을 주는지 알아야 한다. 이 과정을 건너뛰면 에이전트는 그럴듯한 코드를 만들지만, 프로젝트에는 맞지 않는 변경을 할 수 있다.

그래서 개발 보조 스킬의 핵심은 "코드를 잘 생성하는 지시문"이 아니다. 저장소를 읽고, 변경 범위를 좁히고, 위험을 표시하고, 사람의 승인을 받은 뒤 수정하는 절차다. 개발 스킬은 사람 개발자를 대체하는 자동 코더가 아니라, 반복적인 탐색·정리·검토를 줄여 주는 동료처럼 설계해야 한다.

AI 생성 이미지

개발 보조 스킬의 기본 구조

개발 스킬은 다른 업무 스킬보다 승인 지점이 더 중요하다. 파일 하나를 잘못 고쳐도 테스트가 깨지고, 설정 하나를 잘못 바꿔도 배포 장애가 날 수 있기 때문이다.

기본 입력값은 다음처럼 잡는다.

• 저장소 위치 또는 작업 브랜치

• 목표 작업: 탐색, 버그 수정, 리뷰, 테스트 작성 등

• 관련 증상, 에러 로그, 사용자 시나리오

• 수정 가능 범위: 특정 폴더, 특정 파일, 특정 함수

• 금지 조건: 대규모 리팩터링 금지, 의존성 업그레이드 금지, 공개 API 변경 금지 등

• 검증 방법: 실행할 테스트, 빌드 명령, 수동 확인 절차

출력물은 코드만 있으면 부족하다. 좋은 개발 스킬은 다음을 함께 남긴다.

• 읽은 파일과 그 이유

• 의심한 원인과 배제한 원인

• 변경한 파일 목록

• 변경 전후의 동작 차이

• 실행한 테스트와 결과

• 남은 위험과 사람이 확인할 항목

• 롤백 방법

특히 "바로 수정하지 말고 먼저 계획을 제시하라"는 제약이 중요하다. 에이전트가 저장소를 스캔한 뒤 곧바로 여러 파일을 고치기 시작하면, 사람은 변경 의도를 추적하기 어렵다. 개발 보조 스킬은 읽기 단계와 쓰기 단계를 분리해야 한다. 먼저 무엇을 읽었고 무엇을 바꿀 생각인지 설명하게 만든 뒤, 사용자가 승인한 범위 안에서만 수정하게 해야 한다.

스킬 1: 레거시 코드 탐색 스킬

레거시 코드를 처음 만났을 때 개발자는 보통 세 가지를 알고 싶어 한다. 어디서 시작되는가, 어떤 파일들이 연결되어 있는가, 어디를 건드리면 위험한가. 레거시 코드 탐색 스킬은 이 질문에 답하는 스킬이다.

이 스킬의 목적은 코드를 수정하는 것이 아니다. 저장소의 구조와 변경 위험 영역을 빠르게 파악하는 것이다.

트리거

• "이 기능이 어디서 처리되는지 찾아 줘."

• "결제 플로우 관련 파일 구조를 설명해 줘."

• "이 API가 호출되는 경로를 추적해 줘."

• "처음 보는 저장소인데 온보딩용 지도를 만들어 줘."

필수 입력값

• 탐색할 기능 또는 키워드

• 저장소 경로

• 관심 범위: 프론트엔드, 백엔드, 배치, 설정, 테스트 등

• 원하는 출력 깊이: 전체 지도, 특정 플로우, 변경 후보 파일

처리 단계

1. 폴더 구조와 주요 설정 파일을 먼저 읽는다.

2. 애플리케이션 진입점을 확인한다. 예를 들어 라우터, 서버 시작 파일, CLI 엔트리, 배치 스케줄러를 찾는다.

3. 사용자가 준 기능 키워드와 관련된 파일을 검색한다.

4. 호출 관계를 추적한다. 호출자, 피호출자, 이벤트, 라우팅, 설정 주입 경로를 구분한다.

5. 테스트 파일과 문서가 있는지 확인한다.

6. 변경 위험 영역을 표시한다. 공통 유틸, 인증, 결제, 데이터 마이그레이션, 외부 API 연동은 특히 따로 표시한다.

7. 수정 제안이 필요하면 바로 코드를 바꾸지 말고, 변경 후보와 확인 질문을 먼저 제시한다.

좋은 출력 예

사용자 입력이 "쿠폰 적용 로직이 어디 있는지 찾아 줘. 아직 수정하지는 마."라면, 좋은 출력은 다음 구조를 따른다.

• 탐색 요약: 쿠폰 적용은 checkout 화면, couponService, pricing 모듈, 주문 생성 API에서 함께 처리됨

• 주요 파일: 파일명, 역할, 관련 함수

• 실행 흐름: 사용자가 쿠폰 입력 → 검증 API 호출 → 할인액 계산 → 주문 생성 시 재검증

• 테스트 위치: 단위 테스트 2개, 통합 테스트 없음

• 위험 영역: 할인 계산 로직이 포인트 사용 로직과 같은 함수에 있음

• 다음 확인 질문: 쿠폰 정책 변경인지, 버그 수정인지, 테스트 추가가 목표인지

이 스킬의 검증 기준은 "정답 코드를 찾았는가"만이 아니다. 사람이 다음 행동을 결정할 수 있을 만큼 맥락이 정리되었는지가 중요하다. 읽은 파일 목록이 빠져 있거나, 호출 관계를 추측만으로 단정했다면 좋은 탐색이 아니다.

변형 아이디어

• 신규 입사자 온보딩 지도 생성 스킬

• API 요청 흐름 추적 스킬

• 데이터베이스 테이블 영향 범위 분석 스킬

• 프론트엔드 컴포넌트 의존성 지도 스킬

실패 패턴

가장 흔한 실패는 키워드 검색 결과만 나열하는 것이다. 레거시 코드는 이름이 일관되지 않은 경우가 많다. coupon, promotion, discount가 같은 의미로 섞여 있을 수 있다. 두 번째 실패는 탐색 중에 임의로 코드를 고치는 것이다. 탐색 스킬은 읽기 전용이어야 한다. 세 번째 실패는 "이 파일만 고치면 됩니다"라고 과도하게 단정하는 것이다. 호출 관계를 완전히 확인하지 못했다면 "확인 필요"라고 표시해야 한다.

스킬 2: 버그 재현·수정 제안 스킬

버그 수정에서 중요한 것은 빠른 패치가 아니라 재현 가능한 설명이다. 재현 조건이 없으면 수정이 맞았는지 확인할 수 없다. 에이전트가 로그 한 줄만 보고 코드를 바꾸면, 증상은 사라져도 원인은 남을 수 있다.

버그 재현·수정 제안 스킬은 증상 정리, 재현 조건, 의심 원인, 최소 수정안, 회귀 테스트 아이디어를 함께 만든다. 여기서 회귀 테스트란 같은 버그가 다시 생겼을 때 잡아내기 위한 테스트다.

트리거

• "이 에러 로그 보고 원인 찾아 줘."

• "로그인 후 간헐적으로 500이 나."

• "이슈 내용을 보고 수정 계획을 만들어 줘."

• "버그를 고치되 최소 변경으로 해 줘."

필수 입력값

• 증상 설명

• 에러 로그 또는 스크린샷의 텍스트

• 재현 단계

• 기대 동작과 실제 동작

• 실행 환경: 브라우저, OS, 서버 환경, 브랜치, 버전

• 수정 가능 범위와 금지 조건

입력이 부족하면 에이전트는 바로 수정하지 말고 질문해야 한다. "어떤 환경에서 발생했나요?", "항상 재현되나요?", "최근 변경된 파일이나 배포가 있나요?" 같은 질문은 시간을 늦추는 것이 아니라 잘못된 수정을 막는 장치다.

처리 단계

1. 증상을 한 문장으로 정리한다.

2. 재현 조건을 표로 정리한다. 확정된 조건과 추정 조건을 나눈다.

3. 로그와 코드 위치를 연결한다.

4. 의심 원인을 2~4개로 좁히고, 각 원인에 대한 근거를 적는다.

5. 가장 작은 수정안을 제안한다.

6. 수정 전 실패 테스트 또는 수동 재현 절차를 제안한다.

7. 사람 승인 후에만 코드를 수정한다.

8. 수정 후 테스트 결과와 남은 위험을 보고한다.

좋은 출력 예

사용자 입력이 "회원 가입 후 첫 로그인에서만 프로필 API가 404를 반환해. 로그는 첨부했어. 대규모 구조 변경 없이 고쳐 줘."라면, 좋은 스킬은 바로 코드를 생성하지 않는다.

먼저 이렇게 정리한다.

• 증상: 신규 회원의 첫 로그인 직후 프로필 조회 API가 존재하지 않는 프로필 ID로 요청됨

• 확정 조건: 신규 가입 직후, 첫 로그인 직후, 프로필 API에서 404 반환

• 추가 확인 필요: 항상 재현되는지, 특정 브라우저나 서버 환경에서만 발생하는지, 최근 가입·로그인 관련 배포가 있었는지

• 의심 파일: 가입 완료 핸들러, 로그인 콜백, 프로필 생성 서비스, 프로필 조회 API

• 의심 원인: 프로필 생성 완료 전에 세션에 프로필 ID를 기록했거나, 기본 프로필 생성 실패를 무시했을 가능성

• 최소 수정안: 로그인 직후 프로필이 없으면 생성 상태를 확인하고, 없을 때 명시적 생성 또는 대기 응답을 반환

• 테스트 아이디어: 신규 가입 → 첫 로그인 → 프로필 조회 순서의 통합 테스트 추가

그다음 "이 방향으로 수정해도 될까요?"라고 묻는다. 승인 후에는 변경 파일을 최소화하고, 테스트를 실행한 뒤 결과를 보고한다.

변형 아이디어

• 에러 로그 분류 스킬

• 테스트 실패 원인 분석 스킬

• 배포 후 장애 1차 분석 스킬

• 이슈 티켓을 수정 계획으로 바꾸는 스킬

실패 패턴

첫 번째 실패는 증상과 원인을 섞는 것이다. "프로필 API가 문제입니다"는 원인이 아니라 관찰된 증상일 수 있다. 두 번째 실패는 여러 파일을 동시에 리팩터링하는 것이다. 버그 수정에서는 작은 변경이 원칙이다. 세 번째 실패는 테스트 없이 "수정 완료"라고 말하는 것이다. 테스트를 실행할 수 없었다면 실행하지 못한 이유와 사람이 확인할 절차를 남겨야 한다.

스킬 3: 코드 리뷰 체크리스트 스킬

코드 리뷰에서 에이전트가 자주 빠지는 함정은 스타일 지적에 머무르는 것이다. 변수명이 조금 어색하다거나 줄바꿈이 마음에 들지 않는다는 의견은 도움이 될 때도 있지만, 리뷰의 핵심은 위험을 찾는 것이다.

코드 리뷰 체크리스트 스킬은 보안, 성능, 예외 처리, 테스트 누락, 유지보수성을 기준으로 변경 사항을 검토하게 만든다. 사람 리뷰어가 놓치기 쉬운 반복 점검을 맡기는 방식이다.

트리거

• "이 PR 리뷰해 줘."

• "이 diff에서 위험한 부분만 찾아 줘."

• "보안 관점으로 한 번 봐 줘."

• "테스트 누락 여부를 확인해 줘."

필수 입력값

• 변경 diff 또는 PR 링크의 내용

• 변경 목적

• 관련 이슈 또는 요구사항

• 프로젝트의 리뷰 기준

• 특별히 볼 관점: 보안, 성능, API 호환성, 테스트 등

리뷰 기준

• 정확성: 요구사항을 실제로 만족하는가

• 보안: 인증, 권한, 입력 검증, 민감 정보 노출 문제가 없는가

• 성능: 반복 쿼리, 불필요한 네트워크 호출, 큰 데이터 처리 문제가 없는가

• 예외 처리: 실패 경로와 null, 타임아웃, 재시도가 고려되었는가

• 테스트: 정상 케이스뿐 아니라 실패 케이스가 있는가

• 유지보수성: 책임이 지나치게 섞이거나 숨은 의존성이 생기지 않았는가

• 호환성: 공개 API, 데이터 스키마, 설정값 변경이 기존 사용자에게 영향을 주지 않는가

좋은 출력 예

좋은 리뷰 출력은 감상문이 아니라 우선순위가 있는 목록이다.

• 차단 이슈: 배포 전 반드시 수정해야 할 문제

• 질문: 작성자의 의도를 확인해야 판단 가능한 부분

• 제안: 품질을 높이지만 차단은 아닌 개선점

• 테스트 요청: 추가해야 할 테스트 시나리오

• 긍정적 확인: 잘 처리된 부분

예를 들어 결제 API 변경 PR을 리뷰한다면 "코드가 깔끔합니다"보다 "결제 실패 시 재시도 로직이 중복 결제를 만들 가능성이 있습니다. idempotency key 검증 테스트가 필요합니다"가 더 좋은 리뷰다. 에이전트는 말투보다 위험을 우선해야 한다. 다만 확실하지 않은 내용은 단정하지 말고, 어떤 파일이나 코드 흐름을 근거로 그렇게 판단했는지 함께 적어야 한다.

변형 아이디어

• 보안 전용 리뷰 스킬

• 성능 병목 리뷰 스킬

• 테스트 커버리지 리뷰 스킬

• 주니어 개발자 학습용 설명 리뷰 스킬

• 배포 전 체크리스트 리뷰 스킬

실패 패턴

리뷰 스킬의 실패는 크게 세 가지다. 첫째, 사소한 스타일 지적이 너무 많아 중요한 위험이 묻힌다. 둘째, 프로젝트 기준을 모른 채 일반론만 말한다. 셋째, 확실하지 않은 문제를 단정적으로 표현한다. 좋은 리뷰는 "문제입니다"와 "확인 필요합니다"를 구분한다.

변경 범위와 승인 지점을 명시하라

개발 보조 스킬에는 공통 안전 규칙이 필요하다.

첫째, 읽기 단계와 쓰기 단계를 분리한다. 저장소 구조를 파악하고 변경 계획을 제시한 뒤, 사용자가 승인해야 코드를 수정한다.

둘째, 변경 범위를 제한한다. "관련 파일을 모두 개선해 줘" 같은 요청은 위험하다. 스킬에는 "요청한 문제와 직접 관련 없는 리팩터링, 포맷 변경, 의존성 업그레이드, 공개 API 변경은 하지 않는다"는 조건을 넣어야 한다.

셋째, 롤백 안내를 남긴다. 어떤 파일을 되돌리면 되는지, 별도 마이그레이션이나 설정 변경이 있었는지, 테스트 데이터가 바뀌었는지 알려야 한다. 에이전트가 코드를 고쳤다면 사용자는 되돌리는 방법도 알아야 한다.

넷째, 검증 결과를 분리해서 쓴다. "테스트가 통과할 것입니다"와 "테스트를 실행했고 통과했습니다"는 다르다. 실행하지 못했다면 예상이 아니라 미실행으로 표시해야 한다.

마지막으로, 민감한 정보와 운영 환경은 사람이 통제한다. 에이전트가 API 키를 출력하거나, 운영 데이터베이스에 직접 접속하거나, 배포 명령을 실행하도록 두면 안 된다. 개발 보조 스킬은 반복 작업을 줄이기 위한 도구이지, 책임을 사라지게 하는 장치가 아니다.

좋은 개발 스킬은 코드를 많이 바꾸지 않는다. 필요한 만큼만 읽고, 필요한 만큼만 제안하고, 승인된 범위 안에서 최소한으로 수정한다. 이 원칙을 지킬 때 에이전트는 위험한 자동 코더가 아니라 신뢰할 수 있는 개발 보조자가 된다.