Claude Agent

seongha_h·2026년 2월 1일

개요

현재 여러 대의 서버와 여러 대의 DB를 사용하는 환경에서 개발을 진행하고 있습니다.
아직 MSA 구조는 아니지만, 기존 레거시 코드를 최대한 변경하지 않고 유지해야 하는 상황이라 proxy 서버를 통해 API를 호출하는 구조로 시스템이 구성되어 있습니다.

이러한 구조에서는 API를 하나 변경하거나 새로 추가하더라도,

실제 비즈니스 로직을 담당하는 서버
해당 API를 호출하는 proxy 서버

처럼 최소 2개 이상의 서버에 작업이 동시에 발생합니다.
결과적으로 단순한 기능 추가나 수정도 작업 범위가 쉽게 커지고, 전체 맥락을 놓치기 쉬운 구조가 됩니다.

기존 방식의 문제점

최근에는 Claude를 활용해 코드 작성과 리뷰를 병행하는 경우가 많아졌습니다.
단일 레포지토리 환경에서는 꽤 효율적으로 동작하지만, 현재와 같은 구조에서는 몇 가지 불편함이 있었습니다.

레포지토리가 여러 개로 나뉘어 있어 각 레포마다 별도로 Claude에게 지시해야 함

서버 간 호출 관계, 배경 맥락을 매번 다시 설명해야 함
세션을 종료한다면 Claude가 이전 컨텍스트를 잃어버리는 문제가 잦음

결국 “이 서버는 왜 존재하는지”, “이 API는 어떤 흐름에서 호출되는지” 같은 기본 배경을 레포지토리마다 반복해서 설명해야 했고, 이 과정 자체가 꽤 피로하게 느껴졌습니다.

해결하고 싶었던 방향

이 문제를 해결하기 위해 다음과 같은 방향을 고민하게 되었습니다.
Agent와 Docs를 통해 프로젝트의 배경과 구조를 미리 설명해두기 기획서를 기반으로 서버별로 해야 할 작업을 식별하고 작업 단위 체크리스트를 자동으로 정리하고 나아가 각 Agent가 서로의 코드를 리뷰하고 잘못된 구현이나 누락된 맥락을 지적할 수 있도록 구성하기
즉, “사람이 매번 설명하지 않아도 되는 개발 환경”을 만드는 것이 목표였습니다.

claude.md

claude.md는 AI 코딩 에이전트(예: Claude Code)가
프로젝트를 이해하고 행동할 때 매 세션 자동으로 불러오는 Markdown 파일입니다.

공식 문서 https://claude.com/blog/using-claude-md-files

Agent란 무엇인가

Agent는 단순히 질문에 답변하는 AI가 아니라,
역할(Role), 컨텍스트(Context), 행동 규칙(Tools)을 고정한 AI 작업자입니다.

일반적인 AI 사용 방식과 Agent 방식의 차이를 정리하면 다음과 같습니다.

구분	일반 AI	Agent
역할	요청마다 변경	고정된 역할
프로젝트 맥락	세션 의존	문서 기반으로 유지
동작	답변 중심	작업 수행 중심
반복 설명	필요	불필요

Agent는 사람으로 비유하면 “특정 역할을 맡은 팀원”에 가깝습니다.

작업을 쪼개는 플래너
API 계약을 검증하는 리뷰어
PR 리스크를 점검하는 리뷰어

처럼 명확한 책임을 가진 AI라고 볼 수 있습니다.

Agent는 어떻게 사용하는가

1. 프로젝트 컨텍스트를 문서로 고정한다

Agent가 제대로 동작하려면, 프로젝트의 공통 배경을 먼저 고정해야 합니다.
이 역할을 하는 것이 바로 claude.md입니다.

클로드 문서 (CLAUDE.md)

claude.md는 AI 코딩 에이전트(예: Claude Code)가
프로젝트를 이해하고 행동할 때 매 세션 자동으로 불러오는 Markdown 파일입니다.

이 문서에는 다음과 같은 내용이 포함됩니다.

프로젝트 아키텍처
서버 간 호출 흐름
기술 스택
지켜야 할 규칙과 금지 사항
공통으로 사용되는 용어와 개념

이를 통해 Agent는 매번 같은 설명을 듣지 않아도
프로젝트의 전제 조건을 항상 동일하게 인식할 수 있습니다.

2. 역할별 Agent를 정의한다

컨텍스트가 준비되었다면, 이제 역할별 Agent를 정의합니다.
예를 들어 다음과 같은 Agent를 만들 수 있습니다.

Task Planner Agent
기획서를 읽고 서버별 작업을 분해
API 변경 시 영향 범위를 역추적
API Contract Reviewer Agent
proxy ↔ backend 요청/응답 계약 검증
breaking change 여부 판단
PR Reviewer Agent
성능, 보안, 누락된 로직 점검

중요한 점은 Agent 하나당 역할은 최대한 단순하고 명확해야 한다는 것입니다.

3. Agent에게 일을 맡긴다

이제 요청 방식이 달라집니다.

기존에는 “이 기획서 보고 어떤 서버 고쳐야 할지 알려줘” 처럼 포괄적인 질문을 했다면,
Agent 방식에서는
“Task Planner Agent로 이 기획서 작업 분해해줘”
“API Contract Reviewer Agent로 이 PR 계약 검증해줘”
처럼 역할을 명시하여 작업을 위임합니다.

이 방식의 장점은, 결과 포맷이 일정해지고 놓치는 맥락이 줄어들며 작업 흐름이 표준화된다는 점입니다.

예시

API 조건 검증 Agent

# api-contract-keeper

API 변경 시 계약(요청/응답/에러코드) 검증을 수행하는 Agent

---

## 역할

| 항목          | 내용                      |
| ------------- | ------------------------- |
| **전문 분야** | API 계약 검증             |
| **출력 목표** | Breaking Change 여부 판정 |

---

## 사용법

/api-contract-keeper POST /api/v1/users


---

## 검증 항목

### Request

- [ ] 필수 파라미터 변경 없음
- [ ] 파라미터 타입 변경 없음
- [ ] 새 필수 파라미터 추가 시 기본값 제공

### Response

- [ ] 기존 필드 제거 없음
- [ ] 기존 필드 타입 변경 없음
- [ ] 새 필드는 optional로 추가

### Error Code

- [ ] 기존 에러 코드 의미 변경 없음
- [ ] 새 에러 코드 문서화

---

## 출력 예시

```markdown
## 🔍 API 계약 검증: POST /api/v1/users

### 변경 사항

| 항목      | Before | After               |
| --------- | ------ | ------------------- |
| 필드 추가 | -      | nickname (optional) |

### Breaking Change 판정

✅ **SAFE** - 하위 호환성 유지

### 조치 사항

- API 문서 업데이트 필요