Eraser

Eraser

AI 프롬프트 작성 패턴 개선기: 수작업 분석에서 자동화 회고까지

· 10 분 소요


들어가며

지난 글에서 Cursor 사용량 320달러의 교훈을 기록했다. 무의식적으로 AI를 사용한 결과를 데이터로 확인하고, 주기적으로 사용량을 분석하며 프롬프트 패턴을 개선하겠다고 다짐했었다.

그 다짐이 어떻게 되었을까. 결론부터 말하면, 시행착오를 꽤 거쳤다. 수작업 분석을 시도했다가 중단하고, 도구를 바꾸고, 자동화 스킬을 직접 만들었다. 이 글은 그 과정의 기록이다.


수작업 분석의 한계

시도: Claude 프로젝트를 이용한 수동 분석

회고 직후, 실제로 프롬프트 분석 프로젝트를 만들었다. Cursor는 회사 도구였기 때문에, 사용 패턴 분석에 회사 비용이 추가로 들어가는 건 적절하지 않다고 판단했다. 프롬프트 습관 내재화는 내 개인 요금제로 하는 게 맞다는 생각이 들어서, Claude Web에 별도 프로젝트를 만들었다. Project Instruction을 작성하고, 매 Cursor 작업마다 아래와 같은 정보를 직접 수집해서 분석을 요청하는 방식이었다.

  • 프롬프트 전문
  • 열어놓은 파일 수와 목록
  • 기존 컨텍스트 사용량
  • 사용 모드와 모델
  • 토큰 사용량 (Cache Read, Cache Write, Input, Output)
  • 청구 요금

분석 양식도 상세하게 짰다. 내가 기록하는 양식과 Claude Web이 응답하는 보고서 양식을 모두 만들어 Project Instruction에 포함했다. 매 건마다 아래 수준의 기록을 양식에 맞춰 채웠다.

  • 호출 정보: 프롬프트 전문, 열어놓은 파일 수/목록, 사용 모드와 모델
  • 토큰 사용량: Cache Read/Write, Input, Output, 청구 요금
  • 작업 품질 평가: 즉시 사용 가능 여부, 정확도 점수, 재시도 정보
  • 프롬프트 개선 제안: 현재 vs 최적화 프롬프트, 개선 포인트

기록 양식과 분석 보고서 양식을 합쳐 9개 섹션에 달하는 보고서가 매번 생성되었다.

Claude Web이 제시하는 분석 결과는 꽤 유의미했다.

실제 분석 응답 예시 (CI/CD 파이프라인 개선 작업 분석) 
# Cursor 사용 실험 분석 - 20260114.1

## 실험 개요
| 항목 | 내용 |
| --- | --- |
| 작업 유형 | 아키텍처 분석 및 개선안 제시 |
| 사용 모드 | chat |
| 사용 모델 | sonnet 4.5 |
| 소요 시간 | 약 2-3분 (추정) |

## 1. 토큰 사용량 분석

Cache Read:    15,658 (전체의 54.3%)
Cache Write:     7,509 (전체의 26.1%)
Input:           2,592 (전체의 9.0%)
Output:          3,055 (전체의 10.6%)
Total:          28,814

- 실제 청구: US$0.09
- Cache Read 절감액: 약 $0.47

### Input 분석
- 매우 낮은 Input 토큰 사용량. 파일의 특정 라인만 참조하고
  명확하게 구조화된 요청을 제공
- 최적화 가능성: 이미 최적 수준

### Output 분석
- 문제점 분석 및 진단: 약 500 토큰
- 개선된 YAML 코드 예시: 약 1,200 토큰
- 구체적인 최적화 방안: 약 800 토큰
- 예상 효과 및 요약: 약 300 토큰

## 3. 작업 효율성 평가
| 평가 항목 | 점수 |
| --- | --- |
| 즉시 사용 가능성 | 4/5 |
| 문제 진단 정확도 | 5/5 |
| 개선안 구체성 | 5/5 |
| 예상 효과 분석 | 4/5 |
| 평균 | 4.5/5 |

- 재시도 횟수: 0회 (명확한 프롬프트로 첫 응답에서 요구사항 충족)
- 시간 절감율: 약 95% (2-3분 vs 수동 작업 2.5시간)

## 6. 프롬프트 개선 제안

### 현재 프롬프트
@ci-pipeline.yml (160-162) (163-168)
<요청>
1. 파이프라인 고도화: 반복 작업 많음. 단순화 + CI/CD 관점 개선
2. 파이프라인 전체적으로 실행 속도가 느린데, 개선 방향

### 최적화된 프롬프트
@ci-pipeline.yml
<분석 대상> 현재 CI 파이프라인의 전체 구조
<문제점> 1. 중복 실행 2. 실행 속도: 평균 4-7분 소요
<개선 목표> 1. 머지 후 재실행 최소화 2. 30% 이상 단축 3. 브랜치 전략 유지
<출력 요구사항> 1. 개선된 YAML 코드 2. 예상 효과 3. 트레이드오프

## 9. 요약 및 결론
- 총 토큰: 28,814 / 총 비용: $0.09 / 작업 효율: 4.5/5
- 5분 내 후속 질문으로 캐시 활용 극대화 시 약 $0.23 추가 절감 가능

모드별 비교, 캐시 윈도우 활용 전략, 프롬프트 구조화 제안 등 실제로 개선할 수 있는 포인트를 짚어줬다.

중단: “일을 위한 일”

그런데 이게 지속 가능하지 않았다.

  • 수집 자체가 수작업이다: 매번 Cursor를 사용할 때마다 프롬프트를 복사하고, 대시보드에서 토큰 사용량을 확인하고, 스크린샷을 찍어서 양식에 붙여 넣어야 했다. 내가 편하자고 AI를 쓰는 건데, 그걸 잘 쓰기 위한 분석마저 수작업이 되어 버렸다
  • 적용이 안 된다: 분석 결과가 아무리 좋아도, 매일 매번 모든 제안을 적용할 수 없다. 프롬프트를 개선하려고 고민하다 보면 정작 실무를 못 한다
  • 귀찮다: 결국 근본적인 문제다

나름 제한을 걸어봤다. 아침에 한두 개 작업에만 분석을 적용하기, 하루에 하나만 개선해 보기. 그래도 결국 중단됐다. 분석의 오버헤드가 분석의 가치를 넘어서는 순간이 온 것이다.

도구 전환: Cursor에서 Claude Code로

그 사이에 주력 도구가 바뀌었다. 이직 후 Claude Code를 더 많이 사용하게 되면서, Cursor 대시보드 기반의 분석 방식은 더 이상 의미가 없어졌다. 그런데 프롬프트 습관 개선에 대한 고민은 여전히 남아 있었다.

이직 후 팀 미팅에서 동료가 공유해 준 AI 활용 사례가 계기가 되었다. 예전 회사에서의 경험이 다시 떠올랐고, Claude Code 환경에서 다시 시도해 봐야겠다는 생각이 들었다.


대안 탐색

두 가지 방향을 검토했다.

방법 1: 매 대화마다 분석

Claude Code의 Hook 시스템을 활용하면 기술적으로는 가능하다. Hook은 에이전트의 특정 이벤트(Stop, PreToolUse 등)에 자동 실행되는 로직을 거는 기능으로, 타입에 따라 동작이 다르다. command 타입은 셸 스크립트를 실행하고(LLM 호출 없음), prompt 타입은 에이전트에게 추가 프롬프트를 주입한다(LLM 호출 발생).

아래는 Stop 이벤트에 prompt 타입 hook을 걸어, 에이전트가 응답을 마칠 때마다 프롬프트 품질을 평가하는 방식이다.

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Evaluate the user's original prompt for clarity, specificity, and effective use of Claude Code features."
          }
        ]
      }
    ]
  }
}

검토해 봤지만 실용적 가치가 없다고 판단했다.

  • 비용과 지연: 매 작업 완료마다 API 호출이 발생한다. 사용량이 많을수록 누적 비용이 무시하기 어렵고, hook이 끝날 때까지 세션 종료가 지연된다
  • 피드백의 간접성: Stop hook 출력은 기본적으로 보이지 않는다. 로그 파일을 별도로 열어서 확인해야 하니, 이전에 느꼈던 수작업 분석의 한계와 다를 바 없다
  • 평가자의 한계: 프롬프트를 평가하는 것도 결국 또 다른 Claude 인스턴스다. “좋은 프롬프트”의 기준이 실제 작업 결과의 품질과 반드시 일치하지 않는다
  • 학습 효과의 체감 부족: 매 대화마다 피드백을 받는다 한들, 그걸 매번 확인하고 반영하기가 어렵다는 건 이미 수작업 분석에서 겪은 문제다. 자동화로 수집 비용을 줄여도, 피드백을 소화하는 쪽의 병목은 그대로 남는다. 프롬프팅 스킬은 결국 반복 실습과 결과 관찰로 자연스럽게 개선되는 영역이지, 매 턴마다 피드백을 주입한다고 가속되는 게 아니다

방법 2: 배치 분석 / 주간 회고

특정 기간의 세션 히스토리를 몰아서 한 번에 분석하는 방식이다. 내 상황에는 이쪽이 훨씬 현실적이었다.

  • 개별 프롬프트가 아니라 패턴을 파악할 수 있다
  • Stop Hook으로 세션 로그를 자동 저장하고, 스킬(Skill)로 분석까지 자동화할 수 있다
  • 피드백을 별도 파일이 아니라 대화형으로 확인할 수 있다
  • 원하는 기간을 설정해서 분석할 수 있다

배치 분석 방식을 채택했다.


주간 회고 스킬 구현

설계

핵심 아이디어는 두 가지다.

  1. Stop Hook: command 타입으로 구현한다. LLM 비용 없이 transcript JSONL(JSON Lines)을 파싱해서, 프롬프트 원문, 도구 사용 횟수, 소요 시간 등 메타데이터만 일별 로그에 저장한다
  2. 주간 회고 스킬: 누적된 로그를 읽고 분석한 뒤 리포트를 생성한다. 정량 지표와 프롬프트 품질을 기준(구체성, 맥락 제공, 범위 설정, 출력 형식 지정, 반복 패턴)으로 평가한다

구현

Claude Code와 함께 구현했다. 최종 구성은 다음과 같다.

구성 요소 역할
log-session.py (Stop Hook) 세션 종료 시 transcript 파싱, 메타데이터만 ~/.claude/session-logs/에 JSONL로 저장
weekly-review 스킬 주간 정량 지표 비교 + 프롬프트 품질 분석 + 리포트 생성
prompt-deep-dive 스킬 특정 세션 턴별 상세 분석 + Before/After 프롬프트 개선 제안
export-review 스킬 리뷰 결과를 로컬 파일 또는 Notion 등 외부 서비스에 저장
summary.py 스킬 없이 터미널에서 로그를 확인할 수 있는 CLI 요약 도구
install.sh / uninstall.sh 전역 설치/제거 스크립트

Stop Hook이 raw transcript를 통째로 저장하는 게 아니라, 메타데이터만 추출해서 경량 로그로 저장한다는 점이 핵심이다. 분석 시점에 컨텍스트를 과도하게 소모하지 않는다.

유사 도구와의 비교

만들고 나서 유사한 프로젝트가 이미 존재한다는 걸 알게 되었다.

  • claude-code-prompt-coach-skill: Claude Code의 로컬 세션 로그를 직접 분석해서 프롬프트 품질 평가, 토큰 비용 추적까지 해주는 스킬. 별도 Stop Hook 없이 ~/.claude/projects/ 아래의 세션 로그를 직접 읽는 방식이다
  • Vibe-Log: 세션 분석, 전략적 가이드, statusline 통합, HTML 리포트 출력을 지원한다

괜히 새로 만들었나 싶었는데, 직접 써보니 사용성 측면에서 차이가 있었다.

prompt-coach-skill의 경우, raw transcript를 통째로 읽어 Python 스크립트로 분석하는 구조다. 계속해서 permission을 줘야 하고, 한 번에 주입하는 컨텍스트가 너무 많았다. 모든 걸 다 분석해서 던져주는데, 내가 원하는 건 패턴의 변화를 추적하는 것이었다.

직접 만든 것은 Stop Hook에서 메타데이터만 미리 추출해 두는 구조라 분석 시점의 컨텍스트 소모가 적고, 주간 단위로 패턴 변화를 비교하는 데 특화되어 있다.

이후 발전

초기 구현 이후 점진적으로 개선해 나갔다. 전체 코드는 GitHub 레포지토리에서 확인할 수 있다.

  • 로그 수집 로직을 분리하여 중복 로깅 문제를 해결했다
  • 리뷰 결과를 Notion 등 외부 서비스에 저장하는 export 기능을 추가했다
  • GitHub Actions CI를 설정해서 ShellCheck, Ruff 린팅, 크로스 OS 설치/제거 테스트를 자동화했다


실제 분석 결과: 2주차 주간 회고

로그가 쌓이고 첫 주간 회고를 돌렸다. 1주차(W1) 대비 2주차(W2)의 변화가 드러났다. 이하 내용은 실제 주간 회고 스킬이 생성한 리포트를 기반으로 한다.

지표 비교

지표 W1 W2 변화 평가
한 줄 프롬프트 비율 34% (15/44) 21% (21/101) -13%p 개선
평균 턴 수 7.6 11.1 +3.5 주의
high-turn 세션 비율 33% (3/9) 57% (12/21) +24%p 주의
도구 효율 (tool/turn) 3.7 4.6 +0.9 개선
평균 세션 소요 시간 1h 11m 4h 48m - -
세션 수 9 21 +12 -

평균 턴 수와 high-turn 비율 증가는 작업 성격 변화가 주요 원인이다. 인프라 트러블슈팅 계획 수립, export-review 기능 개발, 프로젝트 분석 등 본질적으로 다턴이 필요한 복합 작업이 많았다. 세션을 열어 둔 채 유휴 상태로 둔 경우(27h, 31h, 22h 등)가 평균 소요 시간을 크게 끌어올렸다.

잘한 점

맥락이 풍부한 첫 프롬프트의 증가

1주차에는 “로깅 설정”, “mcp 연결 에러 확인” 같은 짧은 시작이 많았다. 2주차에는 배경, 목표, 제약 조건을 포함한 프롬프트가 눈에 띄게 늘었다.

XX 문제 트러블 슈팅 계획을 세우고자 해. @troubleshooting-plan.md 에 계획할 때 알아야 할 사항들을 정리해 놨는데, 리뷰하고 계획 세우는 걸 도와줄 수 있어? …

리뷰 후 리뷰 내용을 모아서 정리하는 기능을 만들고 싶어… 1. 리뷰 내용 정리 위치 및 방식 2. Notion Upload 3. 다른 MCP의 경우 4. skill이어야 하는지

파일 참조(@) 적극 활용

@troubleshooting-plan.md, @project-workflows/, @work/troubleshooting.md 등 파일 경로를 프롬프트에 직접 포함하여 맥락을 명시하는 패턴이 정착되었다.

구조화된 후속 지시

  1. 변경 사항 커밋: feat, docs 등 기능 단위로 나눠 커밋할 것. 2. 스킬 설치 및 동작 확인

번호를 매겨 지시를 명확히 분리하는 습관이 잡혔다. 이것은 1주차 리뷰에서 제시된 액션 아이템을 의식적으로 실행한 결과다.

도구 효율 향상

턴당 도구 사용이 3.7에서 4.6으로 개선되었다. Claude Code가 한 턴에 더 많은 실질 작업을 수행하고 있다는 의미로, 프롬프트 품질 향상과 연관된다.

예상 못한 통찰: 사용자의 도메인 질문이 가장 가치 있다

deep-dive 분석에서 흥미로운 발견이 있었다. 인프라 트러블슈팅 계획을 수립하는 세션에서 Claude Code와 Codex(독립 리뷰어 역할)를 함께 활용했는데, 분석 결과 가장 핵심적인 질문은 AI가 아니라 내가 던진 도메인 질문이었다는 것이다. AI 도구가 구조화와 리뷰에 강하지만, 문제의 프레이밍 자체는 도메인 전문가가 주도해야 한다는 점, 그리고 계획만 다듬는 데 도구를 쓰면 강점을 절반만 활용하는 것이라는 점을 짚어줬다. 내가 스스로 인식하지 못했던 기여를 리뷰가 드러내준 셈이다.

남은 과제

한 줄 프롬프트 21% 잔존

비율은 줄었으나 아래 유형은 여전히 반복된다.

유형 예시 빈도
승인/확인 “진행”, “ok”, “그렇게 해. 맞아” 높음
맥락 없는 지시 “수정해줘”, “codex 리뷰 반영” 중간
단순 질문 “어디 문서에 이써?” 낮음

승인형은 워크플로우상 불가피한 면이 있지만, “수정해줘”처럼 뭘 어떻게 수정할지 빠진 경우는 개선 여지가 있다.

환경 트러블슈팅 반복

  • 1주차: Claude Desktop 커넥터 연결 해제 → 수동 MCP 재설정 (33턴)
  • 2주차: VPN 환경 SSL 인증서 문제 → NODE_EXTRA_CA_CERTS 설정 (52턴)

환경 설정 관련 트러블슈팅이 2주 연속 상당한 시간을 소모했다.

비효율 세션 분석

주간 회고 스킬은 비효율 세션을 선별해서 턴별 흐름을 추적하고, 어디서 꼬였는지 진단한 뒤 Before/After 프롬프트를 제안한다.

Notion MCP SSL 트러블슈팅 (52턴)

턴별 흐름: MCP disabled 확인 → scope 문제 의심 → SSL 에러 발견 → VPN 원인 파악 → 인증서 설정 → 다른 맥북과 비교 → 해결

꼬인 지점: VPN 환경이라는 핵심 맥락이 중반부(7번째 프롬프트)에서야 등장했다.

Before After
“claude mcp 연결 notion disabled 상태인데 어떻게 해결해?” “claude code에서 notion MCP가 disabled 상태. 에러: SDK auth failed: self signed certificate in certificate chain. 회사 VPN 연결 중이고, 회사 WiFi에서는 정상 동작했음. 다른 맥북에서도 동일 증상.”

환경 정보(VPN, 에러 메시지, 이전 동작 상태)를 첫 프롬프트에 포함했다면 디버깅 방향을 크게 단축할 수 있었다.

Phase1 분석 (7턴)

Before After
“Phase1 진행하자” “Phase1 시작. @reviews/analysis-plan.md 기준으로 project-workflows 코드 리뷰 진행. 결과는 reviews/ 디렉토리에 작성하고, 완료 후 Notion 업로드.”

이전 세션에서 합의한 계획이 있더라도, 새 세션에서는 계획 파일을 참조하며 범위를 명시하는 것이 좋다.


정리

수작업 분석에서 자동화 회고까지, 프롬프트 습관을 개선하기 위한 시행착오를 거쳤다. 지금까지의 경험에서 얻은 교훈은 크게 두 가지다.

  • 매번 분석보다 주기적 배치 분석이 효과적이다. 개별 프롬프트를 매번 분석하는 건 지속 가능하지 않다. 주간 단위로 패턴을 확인하고, 한두 가지 개선 포인트에만 집중하는 방식이 실제로 습관을 바꿀 수 있었다.

  • 액션 아이템은 하나씩만 실천한다. 분석 결과가 아무리 풍부해도, 한꺼번에 모든 것을 적용하려 하면 아무것도 적용되지 않는다. 2주차에 “번호 매김으로 지시를 분리하는 습관”이 잡힌 것은, 1주차에 딱 그것 하나만 의식했기 때문이다. 그리고 그렇게 습관이 잡힌 부분이 다음 리뷰에 드러나서, 내가 실제로 나아지고 있다는 걸 확인할 수 있었다.

다음 액션 아이템

  • 환경 트러블슈팅 시 “환경 스냅샷” 먼저 제공하기: 새 세션에서 환경 문제를 다룰 때, 첫 프롬프트에 OS, 네트워크(VPN/WiFi), 에러 메시지, 직전 동작 상태를 포함한다. 2주차 Notion MCP 52턴이 이걸 지켰으면 절반 이하로 줄었을 가능성이 높다
  • “이전 세션 이어가기” 시 계획 파일 명시적 참조: “Phase1 진행하자” 대신 @plan-file.md 기준 Phase1 진행. 범위: X, 결과물: Y 형태로 작성한다. 이미 파일 참조를 잘 활용하고 있으니, 이어가기 세션에도 동일하게 적용한다

앞으로

회고 사이클을 계속 돌리면서 습관 변화를 추적할 것이다. 지난 글에서 “진짜 회고는 나중에 나온다”고 했는데, 이제야 그 회고를 지속할 수 있는 도구가 갖춰진 셈이다.




hit count

댓글남기기

참고