ASAT(청각 재활 훈련 시스템)와 K3s 홈랩을 운영하는 동안 Claude Code 와 매일 함께 일했다. 처음에는 “코드 자동완성 좀 똑똑한 거” 정도로 썼는데, 6개월 지나니 작업 방식 자체가 바뀌었다 — 코드 직접 치는 시간은 줄고, agent 가 일을 잘 할 수 있는 환경을 만드는 시간이 늘었다.

이 글은 그 6개월 동안 시행착오로 얻은 “AI agent 를 잘 쓰는 법” 7가지 정리. 빌더 관점(어떻게 만드나)이 아니라 사용자/오퍼레이터 관점(어떻게 부려먹나)이다. 이전 글 AI Agent 패턴 비교 — ReAct, Plan&Execute, Self-Reflection 의 뒤집은 시야 정도로 보면 된다.

💡 도구는 Claude Code 기준이지만 — Cursor, Aider, Cline, Copilot Agent 등 다른 agentic CLI 도 동일 원칙으로 통한다.

TL;DR — 7가지 한눈에

# 원칙 한 줄 요약
1 메모리는 누적 자산이다 매 세션 처음부터 설명하지 마라. user/feedback/project/reference 4종으로 누적하라
2 정적 지식과 동적 상태를 분리하라 CLAUDE.md = 아키텍처/컨벤션, STATUS.md = 오늘 무엇이 진행 중
3 작업을 쪼개고 병렬로 던져라 6개 독립 검토 = 6개 서브에이전트 동시 실행. 컨텍스트도 시간도 6배 절약
4 “완료” 라고 말하기 전에 검증을 시켜라 코드 작성과 “이게 정말 동작하나” 확인은 별개의 일이다
5 스킬·하네스를 신뢰하되 stale 항목은 즉시 갱신 메모리는 시점의 사실, 코드는 현재의 사실. 충돌 시 코드가 이긴다
6 모호한 지시는 비용이다 역할·경계·제약을 먼저 잡고 시작해야 결과가 빨라진다
7 Agent 를 도구가 아니라 동료로 대하라 컨텍스트 주면 동료처럼 답한다. 짧게 명령하면 단답으로 끝난다

1. 메모리는 누적 자산이다

대부분의 사람들이 매 세션 처음부터 “내 프로젝트는 ASAT 라는 청각 재활 시스템이고, Java/Spring Boot 4.0.4 에 Next.js 16.2.1 쓰고, 어머니 대상 난청 모드 만들고 있고…” 를 다시 친다. 5분이 매번 사라진다.

Claude Code 의 auto-memory 는 이 비용을 0 으로 만든다. 핵심은 4종 분류 를 의식해서 쌓는 것:

종류 들어가는 내용 예시
user 사용자의 역할·전문성·선호 “10년차 Spring 개발자, React 는 이 프로젝트가 처음”
feedback 교정 받은 행동 + 검증 받은 판단 “DB 모킹 금지 — 작년 마이그레이션 실패한 적 있음”
project 프로젝트 컨텍스트·결정·진행 상황 “K3s 클러스터는 포폴용 홈랩, production 기준 권고 X”
reference 외부 시스템 좌표 “파이프라인 버그는 Linear INGEST 프로젝트 추적”

내 MEMORY.md 일부:

- [텔레그램 채널 주역할 — asat 전용 봇](role_asat_bot.md)
- [K3s 클러스터는 포폴용 홈랩](project_k3s_cluster_homelab.md)
- [서버체크봇 위치/운영](reference_server_monitor.md)
- [ASAT 배포 흐름](project_asat_deploy_flow.md)

효과: 새 세션 열어 “asat 푸시하면 어떻게 배포되지?” 라고 물으면, 메모리에서 helm-deploy + image-updater + ArgoCD 흐름을 곧장 꺼내 답한다. 매번 .github/workflows/* 를 처음부터 grep 안 해도 된다.

⚠️ 함정: 메모리는 시점의 관찰 이다. “X 함수가 Y 한다” 같은 코드 단언을 메모리에 박아두면 리팩토링 후 거짓이 된다. 메모리에는 결정·이유·맥락 만 쌓고, 코드 사실 은 매번 grep 해서 확인하게 해야 한다.

2. 정적 지식과 동적 상태를 분리하라

Agent 가 받는 컨텍스트는 두 부류로 갈린다:

  • 정적: 1년 뒤에도 거의 그대로 — 아키텍처, 도메인 규칙, 기술 스택, 컨벤션
  • 동적: 이번 주에 바뀜 — 현재 진행 중인 작업, 외부 의존 대기, 알려진 이슈

이걸 한 파일에 섞으면 항상 동기화가 깨진다. 분리하면 갱신 비용이 절반 이하로 떨어진다.

ASAT 의 분리:

CLAUDE.md   ← 정적: 도메인(JND 측정 알고리즘), 스택, 13개 엔티티, DR-1~16 도메인 규칙
STATUS.md   ← 동적: "이비인후과 교수 회신 대기", "Phase 1 MSA 사이드카 진행 중"

세션 시작 메시지에 “STATUS.md 먼저 읽고 시작해” 를 박아두면, agent 는 자동으로 최근 컨텍스트부터 흡수한다.

측정 가능한 효과: 매주 갱신해야 하는 라인 수가 1/10 로 줄었다. CLAUDE.md 는 도메인 규칙 추가될 때만, STATUS.md 는 의미 있는 이정표(기능 완료·방향 전환·외부 이벤트) 만.

3. 작업을 쪼개고 병렬로 던져라

가장 임팩트 컸던 변화. ASAT POC 시연 직전에 “품질 스윕” 을 돌릴 때 처음 깨달았다.

기존 방식 (직렬, 1 agent):

보안 점검 → 데이터 export 검토 → 알고리즘 무결성 → 시연 UX → 로딩 처리 → 메뉴 정렬
            (40분, 컨텍스트 누적으로 후반 응답 품질 저하)

서브에이전트 병렬화 (6 agent 동시):

[security-auditor]   [jpa-optimizer]   [audio-engineer]
[frontend-design]    [test-coverage]   [doc-writer]
            ↓ 각자 격리된 컨텍스트, 동시 실행
        결과 6개를 메인 컨텍스트에서 통합
            (8분, 각 agent 가 자기 도메인만 보니 응답 품질 ↑)

핵심은 독립성. 작업끼리 공유 상태가 없거나 순차 의존이 없을 때만 병렬화가 의미가 있다. 잘못된 후보: “리팩토링 한 다음에 그 위에서 테스트 작성” — 이건 직렬.

좋은 후보:

  • 코드베이스 6개 폴더를 각각 다른 agent 가 리뷰
  • 한 PR 에 대해 보안/성능/문서/테스트를 각자 한 명씩
  • 라이브러리 마이그레이션 시 backend / frontend / infra 분리 검토

🛠️ Claude Code 에서는 Agent 도구를 한 메시지에서 여러 번 호출하면 자동 병렬 실행. 메인 컨텍스트는 결과 요약만 받아서 깨끗하게 유지된다.

4. “완료” 라고 말하기 전에 검증을 시켜라

Agent 가 가장 자주 거짓말하는 순간은 “수정 완료했습니다” 다. 코드를 작성했다고 동작하는 건 아니다.

Claude Code 의 verification-before-completion 스킬 핵심: 증거 먼저, 단언 나중. PR/커밋/완료 선언 전에 반드시 다음 중 하나를 보여야 한다:

# 빌드 통과?
./gradlew build -x test    # 또는 npm run build

# 테스트 통과?
./gradlew test --tests SpecificTest

# UI 변경이면 실제로 브라우저에서 클릭해봤나?
npm run dev → 골든 패스 + 에지 케이스 직접 클릭

타입 체크와 테스트가 통과 한다고 기능 이 동작하는 게 아니다. 특히 UI 변경. “빌드 그린입니다” 와 “제가 화면에서 클릭해봤습니다” 는 다른 주장이다.

규칙으로 박아두면 좋은 것:

  • “테스트 없는 코드 변경은 absent. 빌드 통과만으로는 완료 아님”
  • “UI 변경 시 dev server 띄워서 직접 클릭. 못 클릭하면 못 했다 고 말해”
  • “마이그레이션은 real DB 에서 테스트. 모킹 금지”

🎯 실제 경험: ASAT V2 트랙 staircase 알고리즘에서, agent 가 “수정 완료” 라 한 코드가 signedDegrees 직전 trial 부호를 현재 trial 에 저장하는 P0 버그였다. 검증 단계에서 실제로 staircase 한 사이클 돌려봤다면 즉시 잡혔을 것. (지금은 currentSignedDegRef 도입으로 수정됨)

5. 스킬·하네스를 신뢰하되 stale 항목은 즉시 갱신

Claude Code 는 skill 시스템이 있다 — TDD, debugging, brainstorming 등 작업 방식 자체 를 외부화한 모듈. “이 작업은 TDD 로 해” 라고 매번 안 적어도 skill 이 자동 적용된다.

함정은 메모리·STATUS·skill 의 stale 화. 한 달 전에 “수동 배포 필요” 라고 메모리에 적었는데 그 사이 GitOps 가 들어왔으면? Agent 는 계속 잘못된 메모리를 인용한다.

규칙: 메모리·STATUS 항목과 코드 현실이 충돌하면 항상 코드가 이긴다. Agent 가 그 충돌을 발견했을 때:

  1. 즉시 메모리/STATUS 갱신
  2. 사용자에게 “이거 stale 이라 고쳤습니다” 보고
  3. 갱신된 버전으로 답변

오늘 실제 사례: 사용자가 “git push 하면 바로 GitOps 가 쿠버네티스에 반영하나?” 물어봤을 때, STATUS.md 에는 “CI에 deploy 스텝 없음, 수동 배포 필요” 라고 있었다. 하지만 실제 클러스터에 kubectl -n argocd get app asat-prod 찍어봤더니 image-updater + ArgoCD + helm-deploy 레포 흐름이 살아있었다. STATUS.md 는 그 자리에서 갱신, 사용자에게는 최신 흐름 으로 답했다.

📌 단언 전 검증의 두 가지 얼굴:

  • 코드 변경 → 빌드·테스트·UI 클릭으로 검증
  • 기억·문서 인용 → grep·kubectl·실제 파일 확인으로 검증

6. 모호한 지시는 비용이다

“이거 좀 더 좋게 해줘” 는 30분짜리 노이즈를 만든다. 같은 시간이면 다음 두 가지 중 하나로 시작하는 게 낫다:

(a) 명확한 목적 + 제약

"trainee 대시보드 첫 진입 시 로딩이 1초 이상 걸린다.
 - 원인: TanStack Query 로 5개 endpoint 직렬 호출
 - 제약: 백엔드 API 추가는 이번 스프린트 불가
 - 목표: First Meaningful Paint < 600ms"

(b) brainstorming 부터

"trainee 대시보드 진입 경험 좀 개선하고 싶은데,
 무슨 옵션이 있는지 먼저 같이 정리해보자"

(a) 는 곧장 구현 가능. (b) 는 “brainstorming 스킬을 발동하라” 는 신호 — agent 가 옵션 트레이드오프를 늘어놓고, 그 중에서 사용자가 고른 다음에 코드로 간다.

가장 나쁜 패턴은 (a) 가 필요한데 (b) 톤으로 묻거나, (b) 가 필요한데 (a) 처럼 곧장 코드 시키는 것. 컨텍스트가 흐려지고, 결과가 사용자 의도와 빗나간다.

🎯 trick: 지시 보내기 직전에 “내가 지금 무엇을 알고 무엇을 모르는지” 5초만 묻자. 모르는 게 더 많으면 (b), 아는 게 더 많으면 (a).

7. Agent 를 도구가 아니라 동료 로 대하라

가장 추상적이지만 가장 중요한 원칙.

도구 모드 (“AI 가 코드를 짜준다”):

  • 단답형 명령
  • 컨텍스트 0
  • 결과를 그대로 채택 or 폐기

동료 모드 (“AI 와 함께 짠다”):

  • 의도·제약·과거 결정을 공유
  • “왜” 를 묻고 “왜” 를 답한다
  • 결과에 reviewer 로 개입

도구 모드의 천장은 오토컴플리트의 빠른 버전 이다. 동료 모드의 천장은 — 적어도 내 경험상 — 지난주의 나를 디버깅해주는 동료 까지 간다. ASAT 의 P0 staircase 버그를 잡은 것도, K3s etcd leader 가 lemuel 에 자꾸 가는 이유를 진단한 것도, “코드 짜는 도구” 가 아니라 “어제 내가 만든 결정을 다시 검토해주는 사람” 으로 썼기 때문에 가능했다.

동료 모드로 가는 신호:

  • ✅ 메모리에 결정의 이유 가 적혀있다 (Why: … How to apply: …)
  • ✅ STATUS.md 에 대기 항목과 외부 의존 이 명시되어 있다
  • ✅ 한 번 교정한 행동은 두 번 교정하지 않는다 (feedback memory)
  • ✅ Agent 가 잘못된 가정을 발견하면 멈추고 묻는다

도구 모드에 머무는 신호:

  • ❌ “이거 해”, “저거 해” 만 반복
  • ❌ 매 세션 처음부터 다시 설명
  • ❌ 결과를 검증 없이 그대로 머지
  • ❌ Agent 가 “확실치 않다” 고 하면 “그냥 해” 라고 압박

마무리 — 6개월 후

처음에 “Claude Code 쓸 만한가요?” 라고 물으면 “빠른 자동완성이에요” 라고 답했을 거다.

지금 같은 질문을 받으면 답이 바뀐다 — “내 작업의 절반은 agent 가 일을 잘 할 수 있게 환경을 만드는 일이에요.” 메모리 쌓기, STATUS 갱신, skill 정리, 검증 명령 표준화, 서브에이전트 작업 분해. 이게 시간 낭비 가 아니라 복리(複利) 자산 이라는 걸 깨닫는 데 6개월 걸렸다.

도구가 좋아질수록 사용자의 일이 사라지는 게 아니라 상위 레이어로 이동한다. 코드 작성 → 코드 리뷰 → 컨텍스트 큐레이션 → 시스템 설계. AI agent 시대의 시니어 엔지니어는 코드를 잘 짜는 사람 보다 “agent 가 코드를 잘 짜게 만드는 사람” 에 가까워질 것이다.

오늘의 한 줄: Agent 를 잘 쓰는 법은 결국, 어제의 나를 위해 메모를 남기는 법이다.

참고