AI/ML

AI 코딩 에이전트에게 사고 과정을 설계하다— /start부터 Agent Teams까지

2026년 2월 25일

안녕하세요, 백오피스웹개발팀 꼼비입니다.

이 글은 AI 코딩 에이전트를 도입한 뒤, 단순히 “빠르게 코드 생성하기”를 넘어서 에이전트가 어떻게 생각하고 일할지를 설계한 과정을 정리한 글이에요.

Chain of Thought를 결합한 6단계 인지 흐름 모델, .claude/ 기반 규칙 체계, 페르소나별 에이전트 전문화, 그리고 Agent Teams를 활용한 병렬 협업까지- 티켓 하나를 /start로 시작해서 /done으로 마무리하는 워크플로우가 만들어지기까지의 이야기입니다.

1. 왜 체계화를 시작했는지

광고센터 프론트엔드를 혼자 맡게 됐던 그 시점

광고센터 프론트엔드를 혼자 맡게 됐을 때, 가장 먼저 느낀 건 일이 생각보다 훨씬 겹쳐 있다는 거였어요.

일단 시간 부담이 컸습니다.

주문/결제/제휴점 화면을 오가면서 티켓마다 Jira 상태 바꾸고, Figma 확인하고, 파일 뒤지고… 이걸 반복하다 보니 할 일이 한꺼번에 몰리더라고요. 리뷰어도 없으니 최종 검증까지 제가 다 챙겨야 했습니다.

정책이 여기저기 흩어져 있던 것도 문제였어요.

최근 14일이 파일마다 -13인지 -14인지 다르게 계산되고, 필터나 disabled 조건도 제각각이라 규칙이 흔들릴 여지가 있었거든요. 리팩토링하다 정책이 슬쩍 바뀌어도 바로 눈에 안 띄는 구조였습니다.

단일 진실 원칙(Single Source of Truth)이 안 잡혀 있던 것도 아쉬웠어요.

같은 정책이 여러 파일에 복붙되어 있고, 문서도 빽빽하지 않다 보니 새 기능 만들 때마다 과거 구현을 처음부터 다시 추적해야 했습니다.

AI 코딩 에이전트를 도입했지만…

그래서 AI 코딩 에이전트를 붙여봤어요. 생산성은 확실히 올라갔는데, 동시에 새로운 문제도 같이 찾아왔습니다.

에이전트마다 스타일이 달랐어요

import 순서, 상태 관리 방식, styled 패턴이 제각각이었습니다.

비즈니스 규칙을 모르는 채로 시작하는 일이 생겼어요

- last14Days가 13일인지 14일인지, 할인 반올림 기준은 뭔지 헷갈리는 일이 반복되면서 초기 탐색 시간이 늘어났습니다.

같은 피드백을 반복해서 달아야 했어요

리뷰어가 없어서 제가 직접 코드를 검증하다 보니, 같은 포인트를 계속 다시 확인하게 되더라고요.

결국 문제는 “도구가 아니라 방식”이었습니다. 혼자서도 흔들리지 않게 돌아가려면, 운영 기준부터 먼저 세우고 에이전트가 그 기준 안에서 일하게 만들어야 했어요.

“문서만 늘릴 게 아니라, 문서를 코드 흐름으로 옮겨야 한다.”

2. 실제로 이렇게 돌아갑니다

이론부터 설명하기 전에, 완성된 워크플로우가 실제로 어떻게 동작하는지 먼저 보여드릴게요.

/start 한 줄이면 작업이 시작됩니다

티켓 하나를 시작할 때, 터미널에 이렇게 입력합니다.

/start BOWD-42

그러면 에이전트가 자동으로 이 흐름을 실행해요.

Jira 티켓 조회 — 제목, 설명, Figma 링크를 가져오고 상태를 “진행 중”으로 변경
Figma 디자인 분석 — MCP로 디자인 스크린샷과 메타데이터를 조회
코드 분석 — 변경 대상 파일을 탐색하고, Figma와 현재 코드의 차이를 비교
복잡도 판단 — 변경 파일 수와 영향 범위를 보고 LOW / MEDIUM / HIGH 결정

/start BOWD-193 실행화면

복잡한 작업은 서브태스크로 자동 분리됩니다

복잡도가 HIGH로 판단되면, 에이전트가 작업을 서브태스크로 쪼개서 제안해요.

다음 서브태스크를 Jira에 생성할까요? (BOWD-42 하위)
1. OrderInfo 컴포넌트 수정 — 서명상태/할인사유 컬럼 제거
2. PaymentInfo 전면 재작성 — 4열 심플 테이블로 변경
3. CancelInfo 신규 추가 — 취소/환불 정보 섹션
4. ControlPanel 사이드패널 수정 — 340px, 결제일시 조건부 표시
[Y] 생성 / [N] 취소 / [E] 수정

승인하면 Jira에 서브태스크가 생성되고, 각 서브태스크를 독립적인 에이전트가 병렬로 처리합니다.

/start BOWD-60 실행

ai가 생성한 subtask

subtask 내용

/done으로 마무리까지 한 번에

작업이 끝나면 /done BOWD-42를 실행해요. 변경 내용 분석, 정책 검증, lint/build 체크, 커밋, MR 생성, Jira 완료까지 자동으로 이어집니다.

“티켓 시작부터 MR까지, 사람이 직접 반복하던 동선을 커맨드 두 개로 줄인 거예요.”

이제 이 워크플로우가 어떤 원리로 만들어졌는지 풀어볼게요.

3. 접근 방식 — 에이전트의 “사고 과정”을 설계하다

Chain of Thought로 출발했습니다

처음 떠올린 건 Chain of Thought(CoT)였어요. CoT의 핵심은 간단합니다. AI한테 최종 답만 달라고 하지 말고, 추론 과정을 먼저 분해해 달라고 하는 것. 복잡한 문제를 관리 가능한 단계로 쪼개서, 순서대로 결론까지 가게 만드는 방식이에요.

이걸 바로 코딩 에이전트에 적용해봤습니다. “컴포넌트 리팩토링해” 같은 한 줄 지시 대신 “기존 로직 파악 → 영향 범위 분석 → 계획 수립 → 구현 → 결과 검증” 이렇게 순서를 먼저 주니까 반응이 확 달라졌고, 정책 누락이나 범위 밖 변경도 줄어들었어요.

인지적 도제 이론으로 확장했습니다

CoT가 “단계별로 생각하게 하자”라는 기법이라면, 한 발 더 나가서 “그 단계를 어떻게 설계할 것인가”를 고민했어요. 여기서 힌트를 얻은 게 인지적 도제 이론(Cognitive Apprenticeship)이었습니다.

명장이 도제를 가르치는 방식 있잖아요.

시연 → 코칭 → 비계 설정 → 독립. 이걸 빌려왔는데, 에이전트도 마찬가지였어요. 처음부터 “알아서 해”가 아니라, 뭘 먼저 봐야 하는지 체크리스트로 안내하니까 방향이 훨씬 안정적이었습니다.

CoT가 “생각 순서”를 잡아주면, 인지적 도제는 “단계별 체크포인트”를 채워주는 느낌이에요.

6단계 인지 흐름 모델

이 두 가지를 결합해서, 에이전트가 코드에 닿았을 때 바로 적용할 사고 흐름을 만들었습니다.

READ → REACT → ANALYZE → RESTRUCTURE → STRUCTURE → REFLECT

핵심은 복잡도에 맞춰 단계를 조절한다는 겁니다.

작은 변경은 빠르게 처리하고, 정책이 걸린 큰 변경은 분석 단계를 더 가져갑니다.

2번에서 봤던 서브태스크 자동 분리가 바로 HIGH 복잡도일 때 STRUCTURE 단계에서 일어납니다.

4. 설계 — .claude/ 기반 규칙 체계

Single Source of Truth

규칙 원본은 전부 .claude/에 몰아뒀습니다. 에이전트가 달라도 판단 기준은 똑같이 보이도록 룰셋을 한 번 통일해 둔 거죠.

.claude/
├── rules/          ← 코딩 규칙 (7개)
│   ├── core/
│   │   ├── thinking-model.md          # 6단계 인지 흐름
│   │   ├── react-nextjs-conventions.md # React/Next.js 컨벤션
│   │   ├── coding-standards.md        # 코딩 표준
│   │   ├── state-and-server-state.md  # 상태 관리 경계
│   │   └── unit-test-conventions.md   # 유닛 테스트 규칙
│   ├── ad-web/routing-pageinfo.md
│   └── ad-payment/routing-pageinfo.md
├── agents/         ← 에이전트 정의 (6개)
├── commands/       ← 워크플로우 커맨드 (4개)
├── instructions/   ← 지시사항 (10개)
│   ├── multi-agent/    # 병렬 실행, 팀 협업
│   └── validation/     # 금지 패턴, 품질 게이트
└── CLAUDE.md       ← 프로젝트 전체 규칙 (진입점)

3-Tier 규칙 분류

규칙도 다 같은 무게가 아니기에 중요도 기준으로 3단계로 나눴습니다.

예를 들어 Tier 1의 상태 관리 경계 규칙은 이렇게 적용했어요.

서버 상태: TanStack Query (packages/shared/queries/)
전역 UI 상태: Jotai (packages/shared/atoms/)
폼 상태: React Hook Form
로컬 UI 상태: useState/useReducer

이 경계를 넘기면 리뷰 포인트로 바로 잡힙니다. 에이전트도 이 기준에 맞춰서 일하도록 계속 다듬어뒀어요.

도구 통합

팀원들이 광고센터 프로젝트를 작업할때도 각자의 에이전트에 맞는 에이전트 설정 파일을 재생성 하도록 스크립트를 작성했습니다.

Cursor, Copilot, Cline 뭘 쓰든 규칙이 흔들리지 않게 setup-agent.sh로 배포합니다. 규칙 한 번 잡아두면 도구가 바뀌어도 기준은 그대로 유지됩니다.

5. 구현 — 에이전트 전문화와 워크플로우 커맨드

에이전트 전문화: 페르소나로 역할 나누기

에이전트를 “뭐든 다 하는 만능 도구”로 보지 않고, 역할별로 페르소나를 나눠서 썼어요. 도구랑 권한은 역할에 맞게 제한하고, 각자에 맞는 프롬프트로 먼저 가이드합니다. 모델은 에이전트에 고정된 게 아니라 호출 시점에 복잡도 보고 선택해요. 아래는 기본 할당 기준입니다.

explore는 코드 편집 없이 탐색만 해요. 수정은 안 합니다. implementation-executor도 구현 전에 기존 패턴을 꼭 확인하고 들어가고요. 페르소나가 분명해지니까 결과물이 훨씬 예측 가능해졌어요.

워크플로우 커맨드: /start와 /done

2번에서 봤던 흐름의 상세 구조예요. 작업의 시작과 끝을 커맨드로 고정했습니다.

/start {티켓번호} — 작업 시작:

Figma MCP 연결 확인
Jira 티켓 조회 + 상태 “진행 중” 변경
프로파일 분기 (ad-web / ad-payment)
Figma 디자인 분석 (MCP 호출)
코드 분석 + Figma vs 코드 비교
복잡도 판단 → 구현 전략 수립
계획 품질 게이트 통과 확인

/done {티켓번호} — 작업 완료:

변경 내용 분석 + 정책 키워드 탐지
테스트 전략 자동 판단 (컴포넌트/순수함수/UI-only)
코드 검증 (lint, build, 테스트)
릴리스 품질 게이트 (5단계) 통과 확인
커밋 → MR 생성 → Jira 완료

“누가 언제 뭘 했는지”가 다 기록으로 남아요.

복잡도 기반 모델 라우팅

모든 작업에 같은 모델 쓸 필요 없잖아요. 작업 성격에 맞춰 쓰는 게 더 효율적이었어요.

그리고 정책 키워드가 붙으면 규칙 기반으로 모델·검토 깊이를 올려요.

단순 탐색에 opus 낭비 안 하고, 정책 걸린 작업엔 정확도를 우선합니다.

6. 검증 — 정책 보호와 품질 게이트

정책 보호 테스트

비즈니스 규칙은 코드 여기저기 숨어 있기 쉬워서, 리팩토링하다가 조용히 바뀌어버릴 수 있거든요. 그래서 기존 동작을 “캡처”하는 테스트부터 붙여두고 검증하고 있어요.

describe('기간 필터 정책 (회귀 방지)', () => {
  beforeAll(() => {
    jest.useFakeTimers().setSystemTime(new Date('2025-01-15T00:00:00.000Z'));
  });
  afterAll(() => {
    jest.useRealTimers();
  });

  it('last14Days - 오늘 기준 14일 전부터 오늘까지', () => {
    expect(getPeriod('last14Days')).toEqual(['2025-01-01', '2025-01-15']);
  });

  it('thisMonth - 해당 월 1일부터 말일까지', () => {
    expect(getPeriod('thisMonth')).toEqual(['2025-01-01', '2025-01-31']);
  });

  it('lastMonth - 이전 월 1일부터 말일까지', () => {
    expect(getPeriod('lastMonth')).toEqual(['2024-12-01', '2024-12-31']);
  });
});

이 테스트가 깨지면 정책이 바뀐 신호예요. 의도한 변경이면 괜찮고, 아니면 조정이 필요한 거죠.

/done 실행할 때 변경 파일에서 정책 키워드(getPeriod, addDate, disabled, price 등)를 자동 탐지하고, 해당되면 테스트를 강제로 요구해요.

릴리스 품질 게이트 (5단계)

커밋이나 MR 전에 보는 5단계 게이트를 뒀어요.

하나라도 FAIL이면 커밋/PR은 잠깐 멈춥니다. 남는 리스크는 PR 본문에 분명히 적어두는 게 원칙이에요.

금지 패턴

에이전트가 손대면 안 되는 부분도 같이 정리해서 막아뒀어요.

any 타입 사용
@ts-ignore / @ts-expect-error
서버 상태에 useState 사용 (TanStack Query 써야 함)
기존 정책(날짜 계산, 필터 조건) 임의 변경
요청 없이 “더 나은 패턴”으로 코드 변경

작업에 대한 피드백

7. 확장 — Agent Teams로 병렬 협업

Agent Teams란

Claude 기반 멀티 에이전트 기능이에요. 3개 이상의 에이전트가 병렬로 협업하면서 서로 메시지를 주고받을 수 있어요. 앞서 만든 개별 페르소나가 팀으로 조직되는 단계였습니다.

팀 구성 패턴: 페르소나의 팀 편성

서브에이전트 하나하나에 페르소나를 부여한 것처럼, 팀 단위에서도 역할을 명확히 나눠요.

팀 리드 (opus): 계획 수립, 서브태스크 분배, 결과 검증, 평가
  ├── 퍼블리셔 (sonnet): Figma → Emotion/PDS 코드 변환
  ├── 구현 담당 (sonnet): 도메인 핵심 로직 정합성 확보
  └── 리팩토러 (opus): 정책 보호 테스트 → 리팩토링 → 테스트 통과

팀원은 general-purpose로 spawn하되, 프롬프트에서 역할별 스킬 파일을 읽도록 지시해요. 스킬 파일이 페르소나를 결정하는 거죠.

general-purpose + "figma-to-code 스킬 읽어" = 퍼블리셔 페르소나
general-purpose + "refactor 스킬 읽어"      = 리팩토러 페르소나
general-purpose + "bug-fix 스킬 읽어"       = 버그수정 페르소나

각 페르소나는 동일한 인지 흐름(READ → REFLECT)과 규칙 체계를 공유하되, 각자 역할에 집중해요. 인지적 도제 이론으로 사고 과정을 설계해서, 역할을 나눈 동료들을 팀처럼 움직이게 만든 게 포인트였습니다.

2번에서 봤던 서브태스크 분리 → 병렬 실행이 바로 이 Agent Teams 구조에서 일어나는 거예요. 팀리더가 /start를 통해 서브태스크를 만들고 각 태스크를 팀원에게 분배하고 병렬로 진행합니다.

실전 사례

공통 리팩토링 (3명 병렬): packages/shared 마이그레이션을 퍼블리셔, 구현 담당, 리팩토러가 동시에 처리했어요. 각자 서브태스크 나눠 받고 독립적으로 작업한 뒤, 팀 리드가 합쳤습니다.

모노레포 사용에 따른 공통 컴포넌트 생성 및 마이그레이션 계획

PG연동검증: 미구현 항목 확인 및 구현 검증/평가

신규 개발건에 대한 검증 프로세스

API 리뷰 반영 (의존성 순차): enum 인프라 구축 → 서비스/쿼리 연결 → 타입 연결 순서로 진행했어요. 의존성 있는 건 순차로, 독립적인 건 병렬로 처리했습니다.

api 변경건에 대한 변경 계획

팀원 완료 프로세스

팀원이 작업 끝내면 6단계를 거쳐요.

git diff로 변경 범위 확인 (범위 밖 변경 검증)
정책 키워드 탐지
lint/build 검증
커밋 (컨벤션 준수)
Jira 티켓 done
팀 리드에게 결과 보고

교훈: 에이전트도 범위 밖 변경을 할 수 있습니다

실제로 있었던 일이에요. 에이전트한테 “이 파일만 리팩토링해”라고 했는데, variant나 font-size처럼 의도 안 했던 디자인 값까지 건드린 적이 있었거든요. 그래서 팀 리드 체크리스트에 “각 팀원의 git diff 꼭 검증”을 기본 항목으로 넣었습니다.

또 하나, 팀원 spawn하고 관리만 하다 보면 plan 후반의 Jira done, 평가를 놓치기 쉬웠어요. 그래서 단계별 체크리스트를 항상 고정하고, 끝내기 전에 다시 한번 정리해요.

길게 멀티에이전트 돌릴수록 처음 맥락이 조금씩 희미해져요. 끝내기 전에 체크리스트로 한 번 더 정리하는 게 핵심입니다.

8. 결과 — 체계화의 효과

체감한 변화

솔직히 깔끔한 대시보드 수치까지 다 모은 건 아니에요. 대신 실무에서 느껴지는 변화는 꽤 크게 와닿았습니다.

반복 피드백 감소: “import 순서 맞춰주세요”, “서버 상태에 useState 쓰지 마세요” 같은 리뷰 코멘트가 줄었어요. 규칙 파일이 먼저 제시되니까 에이전트가 알아서 확인하고 처리하더라고요.

작업 일관성 향상: 커밋 컨벤션, styled 패턴, 상태 관리 방식이 에이전트가 달라도 비슷하게 유지돼요. 누가 작업했는지 모를 정도로 코드 스타일이 통일됐습니다.

재질문 감소: “근거는 어디서 확인했어?”, “이 정책 기준은 어느 규칙이야?” 같은 질문이 줄었어요. /start로 맥락 잡고 /done에서 검증까지 한 번에 묶으니까 재확인 요청 빈도가 확 줄었습니다.

Agent Teams 병렬 작업: 순차로 하면 3배 걸리던 작업도 병렬로 처리할 수 있었어요. 팀원 의존성만 잘 관리하면 됩니다.

투자 대비 효과

규칙 체계 잡는 데 대략 일주일 정도 걸렸고, 이후엔 매 티켓마다 반복 적용하면서 점점 익숙해졌어요. 덕분에 팀 일관성이 높아졌습니다.

새 도구 도입할 때도 setup-agent.sh 한 번이면 동일한 규칙이 배포돼요. 사람이 바뀌어도, 도구가 바뀌어도 코드 품질 기준은 유지됩니다.

팀 확산 — 범용 규칙 추출

광고센터에서 효과 확인하고 나니까, 자연스럽게 다음 질문이 생겼어요. “이거 다른 프로젝트에도 쓸 수 있을까?”

결론부터 말하면, 가능했습니다. 광고센터 .claude/ 규칙에서 도메인 특화 파트(광고센터 라우팅, 주문 정책, ad-web/ad-payment 프로파일)를 빼고, 범용 규칙만 정리해서 cms-agents 저장소로 옮겼어요.

cms-agents/.claude/
├── rules/core/              ← 범용 코딩 규칙
│   ├── thinking-model.md         # 6단계 인지 흐름 (그대로 적용)
│   ├── react-nextjs-conventions.md
│   ├── coding-standards.md
│   ├── state-and-server-state.md
│   └── unit-test-conventions.md
├── agents/                  ← 6개 페르소나 (그대로 적용)
├── commands/                ← /start, /done 워크플로우
├── instructions/            ← 병렬 실행, 품질 게이트, 금지 패턴
└── CLAUDE.md                ← 프로젝트별로 커스터마이즈하는 진입점

CLAUDE.md만 프로젝트 특성에 맞게 채우면, 인지 흐름 모델·페르소나 기반 에이전트·워크플로우·품질 게이트를 그대로 가져갈 수 있어요.

광고센터에서 다져둔 방식을 다른 프로젝트에 재사용하는 형태죠.

향후 방향

CI/CD 통합: MR 자동 생성, 린트 자동 수정을 파이프라인에 연결
공통 에이전트 설정 동기화 : CMS 뿐만아닌 팀/실에서 사용하는 범용 규칙을 각각 레포지토리에 git subtree와 같은 형식으로 동기화 하는 방안
도메인별 규칙 세분화: 프로젝트마다 정책 키워드, 라우팅 규칙 등을 추가
Skill Registry 반영: 팀원들과 현재 개발중인 skill registry를 cms-agents에 붙여서 인증, 로그, 사용분석 등의 유의미한 아웃풋 생성

마무리

이번 작업에서 가장 크게 느낀 건, AI 코딩 에이전트의 핵심은 도구 자체가 아니라 “어떻게 생각할지”를 설계하는 방식에 있다는 거였어요.

CoT로 사고 순서를 잡고, 인지적 도제 이론으로 단계별 체크포인트를 채우고, 페르소나로 역할을 나누니까 — 에이전트가 무작정 코드를 생성하는 게 아니라, 맥락을 읽고 판단하고 검증하는 흐름 안에서 움직이기 시작했어요.

그리고 그 규칙을 문서가 아니라 코드 흐름으로 옮긴 게 결정적이었습니다. .claude/에 규칙을 모으고, /start와 /done으로 워크플로우를 고정하니까 사람이든 에이전트든 같은 기준으로 움직이게 됐어요. 리뷰할 때마다 같은 피드백을 반복하던 시간이 줄었고, 코드 스타일도 자연스럽게 통일됐습니다.

가장 큰 수확은 이 체계가 이식 가능하다 는 점이었어요. 광고센터에서 다진 인지 흐름 모델, 페르소나, 품질 게이트를 도메인 특화 부분만 빼고 cms-agents로 옮겼더니 다른 프로젝트에서도 그대로 돌아갔거든요. 한 프로젝트에서 쌓은 운영 방식이 팀 전체의 기반이 될 수 있다는 걸 확인한 경험이었습니다.

긴 글 읽어주셔서 감사합니다. 궁금한 점이나 비슷한 경험이 있으시면 편하게 나눠주세요!