Agentic AI 후기 3편 : 실험적으로 알아낸 Claude Code 활용 극대화 전략 5가지

이전 편 : 2025.09.21 - [프로그래밍] - Agentic AI 후기 2편 : Claude Code 한 달 사용 패턴 분석

---

---

Claude Code 활용 극대화하기

Claude Code를 사용하며 개발자가 직접 할 때보다 Agent를 시킬 때 더 효과가 좋았던 사례를 소개하려 한다.
대표적으로 단순 반복 작업 자동화나 문서화, 여러 대안 비교하며 최적 구현 방안 구체화 시키기에 주로 사용하니 효율이 올라갔다.
이를 5가지로 정리해보았다.

1. 에러 해결 반복 자동화
2. 코드 수정에 대한 컨텍스트 유지시키기
3. 요구사항 구체화 시키기
4. 거대한 코드베이스에서 필요한 수정 부분 찾아내기
5. 테스트 케이스 빠르게 만들어내기

또한 이번에 찾아보니 공식 문서에서 프롬프트 엔지니어링 관련 좋은 정보들을 얻을 수 있어, Claude에서도 프롬프트 엔지니어링에 대한 많은 연구가 이루어지고 있다고 느꼈다.

https://docs.claude.com/ko/docs/build-with-claude/prompt-engineering/overview

프롬프트 엔지니어링 개요 - Claude Docs

---

1. 에러 해결 반복 자동화

코드 실행 / 빌드 → 테스트 → 코드 수정 → 실행 → 테스트 사이클을 자동으로 돌리게 하는 것

특히 develop 환경에서는 문제가 없다가 build 환경이나 docker로 올릴 때만 터지는 오류가 몇 개 있었는데, build 시간이 오래 걸리는 경우 개발자가 직접 계속 빌드해보면서 확인하기가 아주 귀찮고 힘들다.

이런 경우, 아래 구조의 프롬프트를 이용해서 오류가 없어질 때까지 claude code에서 자동으로 코드 수정 → build test를 반복하게 하니까 아주 편했다.

문제는 이런 과정을 반복할 때, 수정할 때마다 어디 오류를 수정했는지 컨텍스트가 기록되지 않는 블랙박스여서 나중에 확인할 때 너무 코드 범위가 많고 사람이 놓치기 쉽다는 것이다. 그래서 맨 아래 문장을 추가해 단계 별 변경점을 추적할 수 있었다.

OOO 명령어로 빌드 가능해. OOO 코드로 테스트 가능해. 빌드 시에 OOO 오류가 발생하는 상태인데, 이를 먼저 해결하는 코드를 짜고, 실제로 빌드를 실행한 후에 테스트를 돌려줘. 이를 오류 없이 정상적으로 빌드가 될 때까지 계속 반복해줘.

단, 코드를 수정하고 빌드할 때마다 OOO.md에 어떤 방향으로 코드를 수정했고, 오류의 원인이 뭐였는지 기록해야 해.

특히 웹 개발일 경우, pnpm build하고, 오류 확인하고, 수정하고, 다시 build하고 확인하는 사이클 돌리기도 좋고, docker compose로 빌드하고, 배포하고, 테스트하고, 오류 확인 후 해결까지를 자동화시키기 좋다.

다만 docker compose의 경우 자꾸 최신 명령인 docker compose ~ 가 아니라, 별도 패키지가 필요한 docker-compose ~ 명령을 사용하는 경우가 잦아 claude.md에 전역으로 추가해주었다. 또한 docker compose 파일도 처음 명령 시 명시적으로 지정하는 것이 훨씬 편했다.

## Docker Notes
- docker-compose 대신 docker compose 명령어를 사용할 것.

---

2. 코드 수정에 대한 컨텍스트 유지시키기

사람이 준 task에 대한 코드 수정 이유와 컨텍스트가 기록되지 않아 불편한 점이 많아,
이를 전역 Claude.md에 집어넣었다.

Claude.md에 아래 프롬프트를 입력해두었다.

이를 통해 매일매일 내가 한 일을 훨씬 보기 쉽게 정리할 수 있게 되고, 기존엔 todo와 했던 task를 기록하려면 commit 기록을 던져넣고 claude한테 정리하라고 시켰었는데, 자연어로 매번 정리가 되어 있으니 해온 일과 앞으로 할 일에 대한 컨텍스트 정리가 더 명확해졌다.

## Project Management Guidelines
- 단계별로 todo를 작성해서 업무를 진행하고, 단계를 끝마칠때마다 요약 보고를 출력할 것. 모든 단계를 끝마치면 수정했던 모든 파일들과 어떤 로직을 추가했는지 등을 포함한 총 정리 보고를 할 것.
- todo 한 단계를 완료할 때마다 간략 보고를 출력해야 해.

## 통합된 문서화 및 추적 가이드라인

### 1. 기본 원칙
- 모든 대화와 파일을 수정할 때마다, **수정 목적과 수정 내용에 대한 기록**을 남깁니다.
- 모든 기록은 **한글로 작성**하는 것을 원칙으로 합니다.
- 단, 심각한 보안 사항이나 git에 올라가면 안 되는 사항(api key, password 등)들은 문서화하지 않고, 글로만 출력합니다.

### 2. 저장 위치 및 파일 형식
- 모든 작업 기록 파일은 `docs/daily_work_summary/` 폴더 내에 저장합니다.
- 파일명은 한국 표준시(KST) 기준 작업 날짜를 따라 `YYYY-MM-DD.md` 형식으로 생성합니다. (예: `2025-08-05.md`)
- 한 날짜의 모든 작업 내역은 **해당 날짜의 파일 하나에만 기록**하여 관리합니다.

### 3. 작업 절차 및 내용
- **(사전 확인)** 파일 수정 작업 시작 전, `docs/daily_work_summary/` 폴더에서 오늘 날짜에 해당하는 파일이 있는지 확인합니다.
    - 파일이 존재하면, 내용을 먼저 읽고 충돌이 발생하지 않도록 주의하며 이어서 기록을 추가합니다.
- **(내용 기록)** 파일 안에는 완료된 작업을 구분하여(chapter별) 다음 내용을 기록합니다.
    - **완료 시각**: 해당 작업이 완료된 시각을 한국 표준시(KST) 기준으로 명시합니다. (예: `21:30 KST`)
    - **수정 목적 및 내용**: 어떤 파일을 왜, 어떻게 수정했는지 구체적으로 서술합니다.
    - **(선택) Git 커밋 로그**: `git log` 확인 시 새로운 커밋이 있다면, 해당 커밋 내역을 요약하여 함께 작성합니다.

### 4. 시간 기준
- 문서에 기록되는 모든 시간은 **한국 표준시(Korean Standard Time)**를 기준으로 하며, 시간 뒤에 **'KST'**를 명시합니다.

이를 주위에 알려주고 써본 후기를 들어보니, 토큰 소모량이 너무 많아지고 요즘 claude code 업데이트 이후에 Claude.md에 적어놔도 잘 참고하지 않는다고 한다.

그래서 Claude code 명령어로 만들어두고, 어느 정도는 수동으로 입력하는 방법으로 이 문제를 해결 가능하다.

---

 

3. 요구사항 구체화 시키기

컨텍스트량이 충분하지 않은 상태에서 바로 코드 수정을 시키면 너무 못 짠다.
그런데 반대로 컨텍스트량이 충분히 많이 주어진 상황이라면 코드 수정을 시켰을 때 opus가 아닌 sonnet 모델이어도 코드 수정이 원하는 방향으로 매우 잘 짜여지는 것을 느꼈다.

요즘에는 plan mode로 계속 수정시키면서 구현 계획을 같이 짜는 시간이 80%, 실제 agent mode로 code를 수정하게 시키거나 plan에서 짜여진 코드 수정 계획 기반으로 내가 직접 코드를 수정하는 시간이 20% 이다.

요구사항이 구체화되고 해당 요구사항을 만족시키기 위해 수정해야 하는 코드 부분이 좁혀지면서 plan의 컨텍스트가 충분해지는 시점이 오면 코드 짜는 건 사람이 짜나 AI가 짜나 큰 차이가 없는 것 같다.

기존에는 이 시점까지 도달하려면 다음의 긴 프로세스를 거쳐야 했다. 그런데 AI를 통해 병목 지점을 없앤다면 효율성이 올라가지 않을까? 라는 아이디어로 작업 중이다.

<기존 프로세스>

• stakeholder의 막연한 요구사항
  • 그룹별 유저를 구분하고 싶어요. 그리고 그룹에 속하지 않은 유저만 삭제 가능하게 해주세요.
• PM or 개발자의 요구사항 구체화
  • user에 대한 unsigned group 구분 추가, unsigned user만 삭제되고, 다른 user는 삭제되지 않게 하는 삭제 버튼을 추가해주세요
• FE/BE 개발자의 구현 계획 세우기
  • DB user table에 unsigned group 여부 나타내는 column 추가
  • user table 관리, user API 호출하는 모듈
  • user 관리 page UI의 버튼 추가 위치, 삭제 버튼에 대한 로직
• FE/BE 개발자 실제 구현 & 테스팅
  • 먼저 코드 위치 찾기 → 해당 코드에 추가될 로직 생각하기 → api 추가, 클릭커블 버튼 추가
  • user table에서 unsigned 여부 확인 → 삭제 가능한지 판단 및 삭제해주는 DELETE API 구현 → 해당 API 호출하는 버튼 생성 → 연결 후 테스트

---

여기서 병목이 발생하던 지점은 다음과 같다.

1. 요구사항 구체화
   1. PM이 있는 경우 커뮤니케이션 비용 발생
   2. PM이 없는 경우 개발자가 직접 요구사항을 구체화 해야하는 리소스 낭비 발생
2. 구현 계획
   1. 매우 큰 코드베이스에서 특정 코드의 기존 구현 방법을 이해하는 시간
   2. 이미 구현된 재사용 가능한 로직이 있을지 찾아보는 시간
3. 실제 구현 & 테스팅
   1. 실제 어느 부분에 구현해야 하는지 코드 위치를 찾는 데 걸리는 시간
   2. 로직 추가 이후 사이드 이펙트 없는지 검증 및 testing

이를 정리해보면서 깨달았는데, 요구사항만 명확하면 구현하는 데에는 그리 큰 어려움이 없다는 것이다. 실제로 시간을 따져보아도 단순한 구현 시간보다 “어떻게” “잘” 구현할지 고민하고 자료를 찾아보는 시간이 훨씬 길었다.

그래서 Claude code와 같은 AI Agent를 이용해서 이 요구사항 구체화에 대한 병목을 줄이니까 구현에만 더 집중할 수 있어 업무 효율이 올라가는 경험을 했다.

---

4. 거대한 코드베이스에서 필요한 수정 부분 찾아내기

프롬프트 : “OOO에 관련된 구현을 하려고 하는데, 기존에 어느 부분에서 구현되어 있는지 찾아주고 어떤 방향으로 구현하면 좋을지 검토해줘”

• 특정 코드 부분과 어느 부분에서 수정하면 좋을지 자주 찾아보았다.
• 기존에는 다른 사람들이 관리하던 거대한 코드베이스에서 내가 원하는 기능이 어디에 있는지, 또 이미 구현된 중복 모듈이 있지 않을지 찾아보는 시간이 꽤나 걸렸는데, AI Agent를 시키니 많은 부분이 자동화되어 너무 편해졌다.

---

5. 테스트 케이스 빠르게 만들어내기

• 백엔드 API의 경우 requset data type과 response data type / code가 정해져 있기 때문에 AI를 사용하면 거의 대부분 자동으로 테스트 케이스들을 만들어 낼 수 있었다.
• 프론트엔드의 경우 조금 더 복잡했는데, E2E 테스트나 화면에 대한 테스트를 완전히 자동으로 만들어 낼 수는 없었고 개발자의 더 명확한 지시나 많은 컨텍스트를 AI한테 주어야 했다.

---

<Agentic AI 후기들>

1편 : 2025.09.21 - [프로그래밍] - Agentic AI 후기 1편 : Claude Code 사용법 및 장단점

2편 : 2025.09.21 - [프로그래밍] - Agentic AI 후기 2편 : Claude Code 한 달 사용 패턴 분석

3편 : 2025.10.20 - [분류 전체보기] - Agentic AI 후기 3편 : 실험적으로 알아낸 Claude Code 활용 극대화 전략 5가지