에이전트 환경 구성 1편: 체계적인 개발을 위한 도구들

Claude Code와 Codex를 함께 쓰면서 구성한 코딩 에이전트 작업 환경을 정리한다. 사내 지식 MCP 서버 구현기 1편에서 나를 포함한 팀원들이 이미 Claude Code나 Codex 같은 상용 코딩 에이전트로 개발하고 있다고 적은 적이 있다.

두 에이전트를 계속 쓰면서 필요한 플러그인과 스킬을 하나씩 더해 왔다. 구성이 어느 정도 쌓이자, 각 도구가 어떤 목적과 역할로 들어와 있는지 한 번 정리할 필요를 느꼈다. 정리해 보니 내가 쓰는 도구는 크게 세 범주로 나뉘었다. 세 편으로 나눠 정리한다.

1. 개발을 체계적으로, 잘하기 위해 쓰는 것들 (이 글)
2. 성능을 떨어뜨리지 않고 토큰 소모를 줄이는 것들
3. 업무 효율을 높이기 위해 쓰는 것들

이번 글은 토큰을 조금 더 쓰더라도 설계와 검증을 건너뛰지 않게 만드는 도구들이다. 작업 규모에 따라 superpowers와 GSD 중 하나를 고르게 해 두었는데, 두 도구가 각각 무엇을 해 주는지와 어떤 기준으로 나눠 쓰는지를 중심으로 정리했다.

1. 두 에이전트가 함께 쓰는 구성

지금 Claude Code와 Codex를 함께 쓴다. Claude Code에서는 기본으로 Opus를, Codex에서는 OpenAI 모델을 쓴다. 두 에이전트 모두 다음 방식으로 기능을 넓힐 수 있다.

• 플러그인: 마켓플레이스 등으로 설치하는 확장 기능
• 스킬: 특정 상황에서 불러와 쓰는 작업 지침 묶음
• MCP 서버: 데이터베이스, 사내 시스템, 검색 도구 같은 외부 도구를 에이전트와 연결
• 훅: 세션 시작이나 특정 이벤트가 일어났을 때 정해진 동작을 자동 실행

확장 방식이 비슷해서, 가능한 한 두 에이전트가 같은 구성과 규칙을 공유하도록 맞춰 두었다.

Claude Code와 Codex가 공용 스킬 폴더, 전역 지침, 공용 MCP 서버를 함께 쓰는 구성

지금 쓰는 주요 도구와 역할은 다음과 같다.

이번 글에서는 이 중 개발 절차와 품질 관리에 직접 관여하는 도구를 먼저 다룬다.

2. superpowers: 만들기 전에 먼저 설계하게 하는 플러그인

superpowers는 작업 상황에 맞는 절차를 먼저 불러오게 하는 플러그인이다. 기능을 만들 때는 요구 사항과 설계를 먼저 보고, 버그를 고칠 때는 원인부터 찾고, 완료를 선언하기 전에는 실제 검증을 하도록 안내한다. 예를 들면 이런 일을 줄여 준다.

• 설계 없이 바로 코드를 쓰는 것
• 원인을 찾지 않고 수정부터 하는 것
• 확인하지 않은 채 완료했다고 말하는 것

superpowers를 켜 두면 세션이 시작될 때마다 using-superpowers 스킬 내용이 자동으로 주입된다. 핵심 규칙은, 어떤 스킬이 지금 작업에 적용될 가능성이 조금이라도 있으면 답하거나 질문하기 전에 그 스킬부터 확인하라는 것이다.

주요 스킬은 다음과 같다.

• brainstorming: 기능 추가나 동작 변경처럼 새로운 것을 만들기 전에 쓴다. 바로 구현하지 않고 의도, 요구 사항, 제약, 설계를 먼저 탐색한다.
• writing-plans / executing-plans: 여러 단계로 나뉘는 작업이면 코드를 고치기 전에 계획부터 쓴다. 계획은 실행 단계에서 체크포인트를 두고 순서대로 진행한다.
• subagent-driven-development: 서로 독립적으로 나눌 수 있는 작업이 있으면 현재 세션 안에서 서브에이전트에 나눠 실행한다.
• test-driven-development / systematic-debugging: 기능이나 버그 수정 코드를 쓰기 전에 테스트부터 생각하게 한다. 테스트 실패나 예상 못 한 동작이 나오면 수정안을 바로 내기보다 원인부터 찾게 한다.
• verification-before-completion: 완료됐다, 고쳤다, 통과한다고 말하기 전에 실제 검증 명령을 돌리고 결과를 확인하게 한다.

내가 superpowers를 쓰는 가장 큰 이유도 여기에 있다. 코드를 더 잘 만들게 하기보다는, 개발자가 원래 거쳐야 할 절차를 에이전트도 건너뛰지 않게 만드는 역할에 가깝다.

3. GSD: 여러 날에 걸친 작업을 이어 가기 위한 프레임워크

GSD는 프로젝트를 마일스톤과 phase 단위로 나누고, 진행 상태를 파일로 관리하는 프레임워크다. 내 구성에서 superpowers가 작업 하나를 어떻게 진행할지를 관리한다면, GSD는 여러 세션에 걸쳐 프로젝트 전체를 어떻게 이어 갈지를 관리한다.

GSD는 프로젝트 상태를 .planning/ 폴더에 남긴다. 예를 들어 STATE.md 같은 파일에 현재 진행 상황과 다음 작업을 적어 두니, 세션이 끝나도 다음 세션에서 이어서 작업할 수 있다.

상태가 특정 에이전트의 대화 안이 아니라 프로젝트 파일에 남는다는 점도 중요하다. 덕분에 Claude Code에서 하던 phase를 Codex에서 이어서 처리할 수도 있다.

주로 쓰는 기본 사이클은 다음과 같다.

/gsd-plan-phase N
  ↓
/gsd-execute-phase N
  ↓
/gsd-verify-work N
  ↓
/gsd-ship N

정리하면, superpowers는 지금 작업의 진행 절차를, GSD는 여러 세션에 걸친 프로젝트의 기억과 진행 상태를 관리한다.

4. 둘 중 무엇을 쓸지 고르는 스킬

superpowers와 GSD를 함께 쓰면 판단이 하나 남는다. 이번 작업을 어느 쪽으로 진행할 것인가. 작은 작업에 GSD를 쓰면 너무 무겁고, 큰 작업을 superpowers만으로 진행하면 여러 세션에 걸친 상태 관리가 어렵다.

이 판단을 맡기려고 gsd-or-superpowers라는 개인 스킬을 만들어 두었다. 판단 순서는 이렇다.

1. 기존 GSD 프로젝트인지 먼저 본다. 추론한 맥락보다 프로젝트 상태를 우선한다. .planning/ 폴더가 이미 있으면 기존 GSD 흐름을 그대로 잇는다.
2. 새 작업이면 계획의 크기와 범위를 본다. 계획이 대략 15개 이하의 2~5분 단위 task이고, 저장소 하나나 관심사 하나 안에서 끝나면 superpowers로 진행한다.
3. 작업이 커지면 GSD로 넘긴다. 마일스톤이 여러 개로 나뉘거나, 여러 날에 걸칠 가능성이 높거나, 기존의 큰 코드베이스를 먼저 분석하고 매핑해야 하면 GSD를 쓴다. 특히 코드베이스 매핑은 superpowers에 별도 단계가 없어서 GSD를 쓴다.
4. 애매하면 가벼운 쪽부터 시작한다. 판단이 애매하면 superpowers로 시작한다. 필요하면 나중에 작성된 계획을 /gsd-import로 GSD에 옮길 수 있기 때문이다.

brainstorming 완료 후 .planning 유무와 작업 규모에 따라 superpowers와 GSD 중 하나로 가는 판단 흐름

작업 도중 예상보다 커지는 경우의 처리도 정해 두었다. 일단 작업을 멈추고 왜 GSD로 바꾸는지 한두 문장으로 설명하게 한 뒤, 지금까지의 superpowers 계획을 /gsd-import로 넘긴다.

결국 이 스킬이 판단하는 질문은 하나다.

이 작업을 한 세션 안에서 끝낼 것인가, 프로젝트 단위로 관리할 것인가?

5. code-review: 마지막 점검

개발이 끝나면 code-review 플러그인을 쓴다. 현재 변경이나 PR을 여러 에이전트가 나눠 리뷰하고, 찾은 문제를 확신도에 따라 정리한다. 머지 전에 버그 가능성을 한 번 더 확인하고, 필요하면 수정까지 바로 적용할 수 있다.

/code-review 뒤에는 리뷰 강도를 지정할 수 있다. low와 medium은 확신도가 높은 지적 위주로 적게 내고, high 이상은 더 넓게 검토하면서 상대적으로 불확실한 지적도 함께 낸다. --fix를 붙이면 찾은 문제를 워킹 트리에 바로 고치고, --comment를 붙이면 PR 인라인 코멘트로 남긴다. 나는 이것을 개발 흐름의 마지막 점검 단계로 쓴다.

6. 한계

이 범주의 도구들은 분명히 토큰을 더 쓴다. 스킬을 불러오고, 계획을 문서로 남기고, 중간에 상태를 확인하고, 완료 전에 다시 검증하는 과정이 모두 입력과 출력에 들어가기 때문이다.

같은 코드를 한 번 생성하는 것만 놓고 보면 오히려 비효율적으로 보일 수도 있다. 그래도 지금까지는 토큰을 더 쓰더라도 쓸 가치가 충분하다고 느낀다. 한 번에 빨리 코드를 만드는 것보다, 설계를 먼저 확인하고, 작업을 단계로 나누고, 버그의 원인을 찾고, 실제로 검증한 뒤 끝내는 편이 전체 개발 과정에서는 더 안정적이다.

다만 작은 작업에서는 이런 절차가 오히려 부담이 된다. 그래서 앞의 라우터 스킬도 오탈자 수정이나 한 줄 버그 같은 작업에는 동작하지 않게 했다.

7. 마무리

지금 내 환경에서는 작업 규모에 따라 이렇게 나눠 쓴다.

• 한 세션 안에 끝나는 작업 → superpowers
• 여러 날, 여러 세션에 걸치는 작업 → GSD

어느 쪽을 쓸지는 brainstorming이 끝나고 계획이 어느 정도 잡힌 시점에 개인 스킬이 판단한다. 마지막에는 code-review로 구현된 변경을 한 번 더 확인한다.

다음 편에서는 반대로, 성능은 최대한 유지하면서 토큰 사용량을 줄이는 도구들을 정리한다.