안녕하세요, BasKorea 개발팀장 dongkyu입니다.
부산에서 선박 기자재를 수출하는 무역회사에서 사내 업무 툴 SaaS FlowMate를 만들고 있습니다.

오늘은 저희 팀이 5개월째 실제로 쓰고 있는 개발 에이전트 Flow를 공개합니다.

Flow는 별도 프로그램이 아닙니다. AGENTS.md라는 규칙 문서를 Flow가 읽고, 스스로 판단하고, 경로를 정하고, 단계를 밟아가는 구조입니다.

이 글의 독자는 이런 분들입니다.

• AI 에이전트한테 기능 구현을 맡겨봤는데, 원래 하기로 한 것 말고 딴 게 섞여 나온 경험이 있는 팀

• AI가 PR 쓰고 AI가 리뷰하는 구조를 돌려봤는데, "이거 진짜 검증된 게 맞나"가 남는 사람

• 팀은 작고 쳐내야 할 일은 많아서, AI로 생산성을 진짜 끌어올리고 싶은 개발자

• 직접 코딩은 안 하지만, "이 변경 내가 승인한 적 있었나"가 늘어나는 걸 보는 PM·팀장·CTO

결과부터 말하면, 기능 1개 사이클이 3일에서 4시간이 됐고 저는 코드를 한 줄도 안 칩니다.

불과 1년 전에는 ChatGPT 창에 코드를 복붙하며 손으로 코드를 치던 사람이 쓴 글입니다.

1부. 왜 만들었나

1-1. "하는 김에" 병

AI와 개발하는 팀에 똑같이 찾아오는 증상이 있습니다.

1. 월요일에 "A 기능 추가"로 시작한 작업이

2. 화요일에 "겸사겸사 B 리팩터링"으로 번지고

3. 수요일에 "C 스키마도 손보는 김에"가 되고

4. 목요일엔 원래 해야하는 게 뭐였는지 아무도 모름

AI가 구현이 너무 빨라서, 변경이 일어나는 속도가 승인 주기보다 빠릅니다. 이 지점에서 "대충 다 잘 된 것 같으니 머지하자"는 유혹이 생깁니다.

개발자 설문에서도 66%가 AI 코드를 처음부터 쓰는 것보다 고치는 데 더 많은 시간을 쓴다고 응답했습니다.

저희도 예외가 없었습니다.

세 번 당하고 나서 "이건 코드가 아니라 계약서로 막아야 한다"는 결론에 도달했습니다.

1-2. 기존 방법이 왜 안 됐나

처음엔 흔한 방법들을 시도했습니다.

• PR 템플릿: 작성은 AI가 하고, 리뷰도 AI가 하면 → 체크리스트는 형식적 통과만 남음

• 코딩 가이드라인 md: AI가 "읽었다고 주장"하지만 실제 판단 순간엔 무시되는 경우 다수

• 리뷰어 배정 규칙: 에이전트끼리 리뷰하면 확증 편향 발생 (자기가 만든 걸 자기가 리뷰)

CodeRabbit 분석에 따르면 AI가 쓰고 AI가 리뷰하면 PR당 이슈가 1.7배, 중복 코드가 8배 증가합니다.

또 명령이 너무 많으면 에이전트가 아무것도 제대로 따르지 않는 "지시의 저주" 현상도 발생한다고 합니다.

문제의 본질은 "규칙을 실행하는 주체가 규칙을 이해하지 못한다"는 점이었습니다.

1-3. 결론 — 계약이 필요하다

그래서 AGENTS.md를 하나의 기준 문서로 놓고 세 원칙을 못 박았습니다.

1. 모든 변경에는 명시적 승인이 필요하다. 단 두 문구만 유효 — Approved, LGTM

2. Flow가 구현하고 Flow가 리뷰하더라도, 단계 간 전환은 사람의 명시적 Y/N으로만 이루어진다

3. 범위가 바뀌면 승인이 소멸한다. 재승인 없이 구현 지속은 계약 위반

이 세 줄이 AGENTS.md 최상단에 박혀 있습니다. Flow는 모든 작업 전에 이 세 줄을 먼저 읽습니다.

2부. Flow는 어떻게 판단하는가

2-1. 전체 그림 — AGENTS.md 결정 트리

Flow의 동작은 이 한 장에 다 담겨 있습니다.

세 가지만 먼저 기억하세요.

1. Read-only는 게이트를 안 거친다. 게이트가 모든 요청을 막으면 팀이 쓰기 싫어집니다.

2. Lane은 변경 성격이 정한다. 개발자나 Flow가 "이 정도면 Lightweight"라고 낮춰 부를 수 없습니다.

3. Standard Lane만 A-B-C-D 루프를 탄다. F·L은 Stage D도 없습니다.

Change-executing 요청이 들어오면 Flow는 항상 이 한 문장으로 시작합니다.

경로를 선택하세요: Fast-Track (F) / Lightweight (L) / Standard (N)

변형 없이 무조건 이 형태입니다.

2-2. 어떤 요청이 게이트를 거치는가

게이트 없음 (Read-only)

• Q&A, 조사, 분석

• 로그·쿼리 조회

• 설명, 무변경 리뷰

게이트 필수 (Change-executing)

• 코드·문서 수정

• 구현 연계 테스트·빌드

• DB·쿼리 로직 변경, 커밋

이 구분이 없으면 Flow를 쓰는 게 지겨워집니다.

2-3. F / L / N — 변경 성격이 경로를 정한다

Lane 언제 문서 산출물 F Fast-Track 로직 안 건드리는 수정 없음 L Lightweight 기존 API·DB 그대로, 기능만 추가 README 1개 N Standard API 계약이나 DB 스키마 바꾸는 것 Spec Pack 5개

각 경로는 AGENTS.md에 정의된 게이트를 통과해야만 다음 단계로 넘어갈 수 있습니다.
억지로 경로를 변경하고 싶어도 Flow가 그것을 거절합니다.

3부. 큰 변경일 때 — A-B-C-D

Standard Lane(N)에서는 구현 전에 Spec 5개 문서를 먼저 만들고, 네 단계를 순서대로 밟습니다.

Stage 잠그는 것 핵심 원칙 A 범위 확정 "무엇을 만들지" In/Out 고정, 수용기준 잠금 B 구현·테스트 "무엇을 만들었는지" 승인 범위만 코드화, 테스트 증거 C 반박 리뷰 "무엇이 깨질 수 있는지" 판정만, 코드 수정 금지 D 배포 판단 "운영에서 어떻게 통제할지" Go/No-Go, 롤백·모니터링, 커밋

각 단계 전환은 사람의 Y/N 입력으로만 이루어집니다. Flow가 자의적으로 넘어갈 수 없습니다.

C단계가 핵심입니다.

리뷰 중에 이슈를 발견하고 "이왕 본 김에 고쳐놨습니다"를 하는 순간, 리뷰어는 구현자로 전환됩니다. 판정이 사라지고 재작성만 남습니다.

그래서 C단계는 판정만 — 수정이 필요하면 B단계로 돌아갑니다.

점수 게이트(A→B 85점, B→C 90점, C→D 92점, D→종료 95점)와 하드 게이트(Critical 1개만 있어도 차단)가 이중으로 걸려 있습니다. 세부 내용은 추후 공개할 AGENTS.md 전문에 담겨 있습니다.

4부. 실제로 어떻게 쓰는가

4-1. 4시간 스프린트 — 실무 흐름과 개발 Stage 매핑

실제 Standard Lane 기능 1개를 돌리면 이렇게 흘러갑니다. 왼쪽이 실무 절차, 오른쪽이 그 순간 움직이는 Stage 게이트입니다.

# 실무 단계 Stage 게이트 1 회의·유저 요청 녹음 — (요구사항 수집) 2 녹음 → Flow가 MD 변환 + 해석 — (요구사항 작성) 3 Flow가 Spec Pack 5-file 생성 Route Gate → N 확정 / Stage A 진입 4 백엔드 → 프론트로 api-spec.md 전달 Stage A 계약 교환 5 프론트 에이전트 → 문제·이슈·질문 정리 Stage A 검증 6 백엔드 에이전트 → 질문 분석 → 문서 수정 Stage A 재확정 7 프론트 OK → 각자 에이전트로 개발 + 푸시 Approved/LGTM → Stage B 진입 8 푸시 → 테스트 서버 자동 반영 → 직접 QA Stage C 판정 9 QA 통과 → 운영 배포 Stage D Go/No-Go → commit 10 사용자 피드백 → 다음 사이클 Feature-unit commit 이후

3일이 4시간이 된 이유.

단축의 핵심은 7번(개발)이 빨라진 게 아닙니다.

3~6번(계약)이 명시적이라 다시 안 돌아온다는 점입니다.

예전엔 7번 중간에 "어 이거 스펙에 없는데?"가 터져서 3번으로 복귀했고, 복귀할 때마다 세션·콘텍스트가 휘발됐습니다.

계약이 앞 Stage에서 잠기니 뒤에서 터질 일이 줄었습니다.

4-2. 여기까지 오기까지

처음부터 이렇게 설계된 건 아닙니다.
GitHub에 올라온 유명한 개발 에이전트 구조를 뜯어보고, 설연휴에 "나만의 헤커톤" 이란 이름 아래 혼자 몰아서 작업하면서 지금 버전이 됐습니다.

시점 사건 2025-11 Codex 처음 도입 — 아무 룰 없이 그냥 씀 2025-12 GitHub 오픈소스 에이전트 구조 분석 시작 2026-01 베타버전으로 운영 코드에 슬슬 적용 시작 2026-02 설연휴 명절마다 몰아서 공부하는 루틴 — 이번엔 베타를 운영 수준까지 끌어올림 2026-02 설 이후 100% 에이전트로 코딩 전환 현재 Flow 운영 중

"계약은 코드보다 더 중요하다. 스크립트는 규칙을 실행하고, 계약서는 규칙을 이해하게 한다." — dongkyu

앞으로 각 단계에서 실제로 어떤 방식으로 동작하고, 어떻게 만들어졌는지 하나씩 쓸 계획입니다.

Key Takeaways

1. AI 개발의 위험은 속도가 아니라 승인과 범위가 흐려지는 것

2. 게이트는 과도하면 외면된다 — Read-only 구분이 Flow가 실제로 쓰이는 이유

3. 리뷰어와 구현자는 같은 단계에 있으면 안 된다 — C단계 코드 수정 금지가 이걸 막는다

AGENTS.md v1.4 전문 공개 예정

AGENTS.md 전문은 정리 후 별도 포스트로 공개합니다.

바스코리아 개발팀의 슬로건

"첫 사용자는, 언제나 옆자리 영업 담당자. — dongkyu"