AI 에이전트를 활용한 개발

AI 에이전트 기반 개발은 단순히 코딩을 자동화하는 것이 아니다.
핵심은 AI가 잘 동작하는 환경을 설계하는 것이다.

AI는 매우 강력한 도구지만, 맥락이 부족하면 쉽게 방향을 잃는다.
따라서 AI 시대의 개발자는 더 이상 단순한 구현자가 아니라 작업을 구조화하고 맥락을 설계하는 사람이 된다.

실제 AI 에이전트를 활용하면서 효과적이었던 몇 가지 원칙을 정리했다.

---

1. AI에게 충분한 맥락(Context)을 제공하라

AI의 결과 품질은 맥락의 품질에 정비례한다.

단순히 기능을 요청하는 방식은 좋은 결과를 만들기 어렵다.

좋지 않은 요청 예시

이 기능 만들어줘

 

좋은 요청 방식

이 기능을 만들려고 한다.
현재 시스템 아키텍처는 다음과 같다.

- 인증 방식: 세션 기반
- 상태 관리: 서버 중심
- API 레이어: BFF 구조

이 맥락을 기반으로 구현 접근 방식을 먼저 제안해주고
내가 놓치고 있는 엣지 케이스가 있으면 함께 알려줘.

 

이렇게 문제 정의 → 접근 방식 논의 → 구현 순서를 따르면 결과의 질이 크게 달라진다.

핵심은 AI를 단순한 코드 생성기가 아니라 협업 대상으로 다루는 것이다.

---

2. 프로젝트의 의도를 문서로 명확히 전달하라

AI는 코드만 보고도 많은 것을 추론하지만,
아키텍처 결정의 맥락까지 완전히 이해하지는 못한다.

그래서 프로젝트에는 AI가 참고할 수 있는 명확한 기준 문서가 필요하다.

대표적으로 다음과 같은 문서를 유지하는 것이 효과적이다.

AGENTS.md (또는 agent.md)

이 문서에는 다음 정도만 포함하는 것이 좋다.

• 아키텍처 결정 이유 (ADR)
• 코딩 컨벤션
• 도메인 용어 사전

예를 들면

- 인증: 세션 기반
- BFF 레이어에서 외부 API 호출
- domain layer에는 side-effect 금지

 

이런 맥락을 제공하면 AI의 코드 스타일과 설계가 훨씬 일관되게 유지된다.

다만 중요한 점이 하나 있다.

좋은 코드 자체가 최고의 문서다.

• 타입 정의가 정확하고
• 함수 이름이 의미를 담고 있으며
• 테스트가 스펙 역할을 한다면

그 자체가 AI에게 가장 강력한 맥락이 된다.

---

3. AI가 이탈하지 못하도록 제약을 설계하라

AI는 자유도가 높을수록 엉뚱한 방향으로 갈 가능성도 높아진다.

그래서 중요한 것은 제약 조건을 먼저 설계하는 것이다.

대표적인 방법은 다음과 같다.

• 테스트 케이스
• 타입 시스템
• 린트 규칙
• 정적 분석

이런 제약이 있으면 AI는 자연스럽게 문제 공간 안에서만 탐색하게 된다.

즉

좋은 테스트 = 좋은 가드레일

이다.

---

4. 작업을 작게 쪼개고 체크포인트를 만든다

AI와 협업할 때는 작업 단위를 작게 유지하는 것이 중요하다.

예를 들어 글을 작성할 때도 다음처럼 진행할 수 있다.

목차를 먼저 만들어줘
→ 1장만 작성해줘
→ 2장까지 확장해줘
→ 전체 흐름을 정리해줘

 

개발 작업도 동일하다.

좋은 워크플로우 예시

1. 기능 정의
2. UI 설계
3. 동작 명세
4. 엣지 케이스 정의
5. 구현
6. 테스트

이렇게 단계별 체크포인트를 두면
AI가 잘못된 방향으로 가는 것을 조기에 발견할 수 있다.

---

5. 구현 전에 AI와 “인터뷰”하라

AI를 가장 잘 활용하는 방법 중 하나는 구현 전에 계획을 논의하는 것이다.

예를 들어 다음과 같은 질문을 할 수 있다.

이 기능을 구현하기 전에 내가 고려해야 할 것이 무엇일까?

 

또는

이 설계에서 발생할 수 있는 잠재적인 문제를 찾아줘

 

이 과정은 마치 시니어 개발자에게 설계를 리뷰받는 과정과 비슷하다.

구현 전에 이런 대화를 거치면 설계 품질이 크게 올라간다.

---

6. AI 작업은 병렬로 관리할 수 있다

에이전트 기반 개발의 또 하나의 장점은 병렬 작업이다.

예를 들어 다음과 같이 나눌 수 있다.

• 창 1 → API 구현
• 창 2 → 테스트 작성
• 창 3 → 문서 정리

AI 에이전트는 동시에 여러 작업을 수행할 수 있기 때문에
작업 처리량이 크게 증가한다.

---

7. 실패했을 때는 원인을 분석해야 한다

AI 결과가 이상할 때는 단순히 다시 요청하는 것보다
왜 실패했는지 분석하는 것이 중요하다.

예를 들어 다음과 같이 접근할 수 있다.

1. 결과가 나온 이유 분석
2. 필요한 정보 추가 수집
3. 문제 해결 전략 논의
4. 수정된 프롬프트 재실행

이 과정은 사실 일반적인 디버깅 과정과 동일하다.

---

8. 인간의 역할은 오히려 더 중요해지고 있다

AI가 코드를 많이 작성하게 되면서
개발자의 역할은 점점 더 상위 레이어로 이동하고 있다.

개발자는 이제 다음을 읽어야 한다.

• 스펙
• 아키텍처
• 테스트 결과
• 도메인 맥락

코드는 점점 구현 세부사항이 되어가고 있다.

하지만 여기서 중요한 사실이 하나 있다.

코드를 읽는 능력은 오히려 더 중요해졌다.

모든 테스트가 통과하는데도 제품이 이상하게 동작할 때
여러 에이전트가 해결하지 못하는 버그가 있을 때

결국 시스템 전체 흐름을 이해하고 코드를 직접 읽어야 하는 순간이 온다.

---

9. 핵심 코드는 여전히 인간이 책임진다

AI가 만든 코드라도 모든 것을 그대로 신뢰할 수는 없다.

실제로 AI 개발 도구를 만드는 팀들도 다음과 같은 원칙을 유지한다.

• 비핵심 코드 → AI 리뷰 중심
• 핵심 코드 → 인간 코드 리뷰 필수

특히 다음 영역은 사람이 직접 확인하는 것이 중요하다.

• 인증
• 보안
• 데이터 무결성
• 핵심 도메인 로직

---

10. AI는 개발자의 역량을 증폭시킨다

AI는 능력을 대체하기보다는 증폭한다.

• 비판적인 사람 → 더 좋은 설계
• 창의적인 사람 → 더 다양한 해결책
• 깊이 있는 개발자 → 더 복잡한 시스템

반대로 코드 이해도가 낮다면
AI를 사용해도 동작은 하지만 쉽게 깨지는 시스템이 만들어질 가능성이 높다.

---

결론

AI 시대의 핵심 역량은 코드를 더 빨리 쓰는 능력이 아니다.

핵심은 다음 세 가지다.

1. 맥락을 설계하는 능력
2. 작업을 구조화하는 능력
3. 시스템을 판단하는 능력

그리고 무엇보다 중요한 것은 이것이다.

AI가 잘 동작하는 조건을 설계하는 능력

이 능력이 앞으로 개발자의 가장 중요한 경쟁력이 될 가능성이 높다.

 

 

 

3. 분업 시키기: 동시에 여러 개를 돌려라

4. 클로드 전용 메모장을 만들고 지속 업데이트해라

5. 단축 명령어를 써

6. 작업을 이어서 해야하는 경우 현재 세션의 내용을 요약해서 파일로 저장하도록 요청해라

7. 클로드가 일을 끝냈을 때 알림을 받아라