BAS KOREA

안녕하세요. BAS KOREA IT팀에서 Flow MATE를 만들고 있는 INSIK HWANG입니다.

이 글은 운영 중인 레거시 서비스를 AI가 주도해서 새 모노레포로 옮기기 위해, 단순히 프롬프트를 길게 쓰는 대신 AI가 길을 잃지 않게 만드는 작업 운영체제를 어떻게 설계했는지 정리한 글이에요.

처음에는 "AI가 코드를 얼마나 잘 짜느냐"가 핵심이라고 생각했습니다. 그런데 실제 운영 서비스를 대상으로 마이그레이션을 시작해 보니, 더 중요한 질문은 따로 있더라고요. AI가 지금 어디까지 왔는지 알고 있는가. 무엇을 건드리면 안 되는지 알고 있는가. 완료라고 말하기 전에 어떤 증거를 남겨야 하는가.

결국 문제는 도구가 아니라 방식이었습니다.

1. 왜 시작했는지

Flow MATE는 이미 실제 사용자가 있는 운영 서비스였습니다. 업무 흐름은 Inquiry에서 시작해 Offer, Order, Logistics, Invoice로 이어집니다. 프론트엔드, 백엔드, 파서가 각각 중요한 역할을 맡고 있었지만, 레포와 언어가 나뉘어 있었습니다.

기능 하나를 고치려면 프론트 레포를 보고, 백엔드 레포를 보고, 필요한 경우 파서까지 확인해야 했습니다. 사람도 API 이름과 변수명을 맞추기 어려웠고, AI는 더 쉽게 문맥을 잃었습니다.

백엔드는 Java Spring 기반이었습니다. Java가 나쁘다는 이야기는 아닙니다. 다만 AI 주도 반복 작업에는 피드백 루프가 무거웠습니다. 간단한 변경도 Controller, Service, DTO, Entity, Repository를 오가야 했고, 컴파일과 기동 시간이 길면 "바로 고치고 바로 검증"하는 리듬이 끊겼습니다.

가장 큰 제약은 운영 서비스라는 점이었습니다. 이미 사용자가 있고, 기존 배포와 운영 DB, AWS, 도메인, 시크릿을 실험 대상으로 삼을 수는 없었습니다. 그래서 방향은 명확했습니다. 기존 운영은 무영향으로 두고, 신규 시스템을 병행으로 만든다.

<!-- AGENTS.md -->
- legacy/ 폴더는 read-only 참조 자료다.
- 운영 DB/AWS는 분석 목적의 read-only 조회만 허용한다.
- 운영 트래픽과 배포 설정은 사용자 승인 전 변경하지 않는다.
- 신규 시스템은 별도 구조에서 병행 검증한다.

AI에게 일을 맡기려면, 먼저 AI가 안전하게 일할 수 있는 길을 깔아야 했습니다.

2. 실제로 어떻게 돌아가는지

이론부터 설명하기 전에, 새 AI 세션이 실제로 어떻게 시작되는지 먼저 보여드릴게요. Flow Mate 레포에서 세션이 시작되면 AI는 저에게 "어디까지 했나요?"라고 묻지 않습니다. 먼저 정해진 파일을 읽습니다.

<!-- AGENTS.md -->
1. AGENTS.md
2. docs/STATUS.md
3. ROADMAP.md
4. docs/migration/handoff/stage-XX-handoff.md
5. 현재 단계의 입력 산출물

docs/STATUS.md는 지금 단계와 차단 사항을 알려줍니다. ROADMAP.md는 현재 [>] 단계가 어디인지 보여줍니다. handoff 문서는 직전 세션이 무엇을 했고, 어떤 질문을 남겼고, 다음 세션이 어디서 이어야 하는지를 알려줍니다.

세션이 끊겨도 맥락이 끊기지 않게 만든 거예요. 사람이 다시 설명하는 대신, 문서가 다음 AI에게 인수인계를 합니다.

단계 5의 구현 흐름도 작게 쪼갭니다.

<!-- ROADMAP.md / 단계 5 -->
1. spec 재확인
2. 슬라이스 계획 문서 작성
3. 테스트 먼저 작성
4. 구현
5. legacy 동작 비교
6. feature delta 기록
7. INDEX 상태 갱신
8. lint/typecheck/test 검증
9. 커밋

자율 구현을 맡길 때는 병렬 lane을 검토합니다. 하지만 기준은 "많으니까 병렬"이 아닙니다. 쓰기 파일이 겹치지 않고, 순서 의존이 없고, 서로의 산출물에 기대지 않을 때만 병렬로 보냅니다.

서브에이전트는 직접 파일을 쓰지 않습니다. 최신 상태를 읽고 draft를 반환합니다. 메인 AI만 실제 파일을 수정하고, 검증하고, 커밋합니다. 이 규칙 덕분에 속도는 가져가면서도 책임 지점은 하나로 유지할 수 있었습니다.

3. 접근 방식 또는 사고 모델

이 프로젝트를 하면서 가장 와닿았던 표현은 하네스 엔지니어링이었습니다. AI를 더 똑똑하게 믿는 게 아니라, AI가 위험한 방향으로 튀지 못하게 하네스를 씌우는 쪽에 가깝습니다.

핵심은 간단합니다.

"AI에게 더 긴 프롬프트를 주는 대신,
AI가 반복해서 안전하게 일할 수 있는 실행 환경을 만든다."

Flow Mate에서는 이 실행 환경을 AI 작업 운영체제처럼 봤습니다. AGENTS.md는 헌법입니다. ROADMAP.md는 지도입니다. docs/STATUS.md는 현재 위치판입니다. handoff는 다음 세션을 위한 인수인계서입니다. docs/specs/INDEX.md는 기능 누락을 막는 계약서이고, feature-deltas.md는 레거시와 달라진 동작을 숨기지 않는 장부입니다.

사람과 AI의 역할도 분리했습니다. AI는 레거시 분석, spec 작성, 구현, 테스트, 문서 갱신, 커밋까지 맡습니다. 대신 스택 선택, 운영 영향, 보안 정책, DB 전환 방향, 단계 종료 gate 같은 핵심 판단은 사람이 봅니다.

AI가 운전대를 잡는 시간이 많아졌지만, 목적지와 금지 구역은 사람이 정해야 했습니다.

4. 설계 구조

문서는 부록이 아니라 실행 인프라였습니다. AI가 지금 당장 읽고 판단해야 하는 입력이기 때문에, 문서 구조도 코드 구조만큼 중요했습니다.

<!-- FlowMate 마이그레이션 운영 구조 -->
AGENTS.md
ROADMAP.md
docs/
├── STATUS.md
├── specs/
│   ├── INDEX.md
│   └── *.md
└── migration/
    ├── handoff/
    │   └── stage-05-handoff.md
    ├── plans/
    │   └── *-slice-plan.md
    ├── validation/
    │   └── feature-deltas.md
    ├── reviews/
    │   └── stage-XX-gate-review.md
    └── decisions/
        └── *-decision.md

AGENTS.md는 AI가 반드시 지켜야 할 규칙의 정본입니다. ROADMAP.md는 단계를 건너뛰지 않게 합니다. docs/STATUS.md는 새 세션이 현재 위치를 바로 알게 합니다. handoff 문서는 보고, 질문, 답변을 다음 세션으로 넘깁니다.

그중에서도 docs/specs/INDEX.md는 기능 누락을 막는 계약서였습니다. 프론트 route, API 호출, 백엔드 mapping, job, parser endpoint, DB 객체를 대조해 전체 기능을 잡습니다. 이 숫자는 자랑용이 아닙니다. AI가 "주요 기능은 옮겼다"고 말하지 못하게 만드는 방어 장치입니다.

INDEX는 "대충 옮겼다"를 막기 위한 계약서였습니다.

5. 구현 방식

처음부터 완벽한 규칙이 있었던 것은 아닙니다. AI에게 자유롭게 맡기면 빠르긴 했지만, 어느 순간 문제가 생겼습니다. 문서를 갱신하지 않거나, 검증 없이 완료라고 말하거나, 중요한 결정을 추정으로 처리하거나, 요청 범위 밖 변경을 만들 때가 있었습니다.

그래서 AGENTS.md가 커졌습니다. 중요한 제약은 꽤 직접적입니다.

<!-- AGENTS.md 핵심 제약 요약 -->
- C4. 모든 작업은 문서를 동반한다.
- C6. legacy/ 폴더는 read-only 참조 자료다.
- C8. AI는 자율 진행하되, 핵심 결정은 사용자에게 묻는다.
- C10. 사용자와 주고받은 모든 내용은 파일로 저장한다.
- C16. 완료 보고 전 lint와 typecheck를 통과한다.
- C18. PASS는 자동 검증 가능한 증거 기반으로만 선언한다.
- C20. 자율 구현은 병렬 lane 오케스트레이션을 기본으로 한다.

마이그레이션 단계도 작게 나눴습니다. 작업 공간 셋업, 레거시 분석, 스택 결정, 모노레포 골격, 기능 스펙, DB 재설계 기반, 수직 슬라이스, 동등성 검증, 병행 배포 검증으로 이어집니다.

각 단계는 입력과 산출물이 있고, 단계 종료에는 gate review가 있습니다. 특히 구현 단계에서는 기능 하나를 슬라이스로 쪼개고, 슬라이스마다 계획 문서와 테스트, 구현, 검증, 문서 갱신, 커밋을 남깁니다.

병렬 lane에서는 역할을 더 엄격히 나눴습니다.

공유 chokepoint는 메인이 직렬로 처리합니다. 예를 들면 Prisma schema, app module, shared barrel export, lockfile, STATUS, ROADMAP 같은 파일입니다. 병렬화는 도움이 되지만, 병합 지점이 흐려지면 검증 비용이 더 커집니다.

6. 검증 체계

AI의 자신감보다 검증 로그를 믿는 방식으로 가야 했습니다.

코드 작업의 기본 gate는 단순합니다.

<!-- repo root -->
pnpm lint
pnpm typecheck

UI 작업이면 pnpm lint:ui를 추가하고, 단계 gate에서는 pnpm verify:migration-gate를 봅니다. 변경 범위에 맞는 focused test도 같이 돌립니다.

하지만 검증은 명령어만의 문제가 아니었습니다. 무엇을 보호하기 위한 검증인지가 중요했습니다.

• 변경 범위가 요청과 맞는가

• legacy/가 수정되지 않았는가

• 운영 DB/AWS는 read-only 원칙을 지켰는가

• 레거시와 달라진 동작은 feature-deltas.md에 기록했는가

• PASS라고 말할 자동 검증 증거가 있는가

• 단계 종료라면 독립 subagent gate review가 있는가

특히 PASS는 감상이 아니라 증거여야 했습니다. AI가 "완료했습니다"라고 말해도, 어떤 범위를 검증했는지와 어떤 로그가 남았는지가 없으면 완료가 아닙니다.

운영 무영향도 같은 맥락입니다. 실제 사용자가 있는 서비스에서는 "할 수 있다"와 "해도 된다"가 다릅니다. 기술적으로 가능한 작업이라도 운영에 영향을 줄 수 있으면, 명시적인 승인 전에는 하지 않는 것이 원칙입니다.

7. 확장 사례

이 구조가 어느 정도 안정되자 자연스럽게 다음 질문이 생겼습니다. "이거 다른 작업에도 쓸 수 있을까?"

Flow Mate에 특화된 도메인 지식은 바뀌어도, 아래 규칙은 다른 프로젝트에도 옮길 수 있습니다.

현재 이 기술 블로그 작성 흐름도 같은 구조를 따릅니다.

<!-- docs/tech-blog workflow -->
docs/blog/series-01-ai-for-ai-migration-interview-clean.md
  → tech-blog-source
  → docs/tech-blog/blog-source/01-ai-for-ai-migration-blog-source.md
  → tech-blog-post
  → DynamoDB JSON

1차 소스는 근거와 작성 지시를 보존합니다. 본문 JSON은 발행 포맷에 맞춥니다. 글이 마음에 들지 않아도 근거 문서를 다시 만들 필요가 없습니다.

8. 결과와 효과

솔직히 모든 효과를 대시보드 수치로 모은 건 아닙니다. 대신 실무에서 느껴지는 변화는 꽤 분명했습니다.

첫째, 새 세션 재설명 비용이 줄었습니다. 세션이 끊겨도 AI가 AGENTS.md, STATUS.md, ROADMAP.md, handoff를 읽고 바로 이어서 작업합니다.

둘째, 기능 누락을 방어할 수 있게 됐습니다. docs/specs/INDEX.md가 전체 기능 목록을 잡고 있으니, AI가 구현하기 쉬운 것만 먼저 하고 나머지를 잊는 일을 줄입니다.

셋째, 병렬 작업이 가능해졌습니다. 쓰기 파일이 겹치지 않는 lane은 서브에이전트 draft로 병렬 처리하고, 메인이 통합합니다. 여러 에이전트가 동시에 파일을 쓰는 방식보다 느려 보일 수 있지만, 실제로는 검증과 회귀 비용이 줄어 더 안정적이었습니다.

마지막으로 사람의 집중 지점이 바뀌었습니다. 사람이 모든 구현을 붙잡고 있지 않아도 됩니다. 대신 방향이 맞는지, 운영에 영향이 없는지, 보안 정책을 어기지 않았는지, 단계 gate를 넘겨도 되는지를 봅니다.

AI가 일을 대신해 주는 만큼, 사람은 더 중요한 결정에 집중해야 했습니다.

9. 마무리

AI에게 마이그레이션을 맡겼더니, 제일 먼저 한 일은 AI가 길을 잃지 못하게 울타리를 치는 일이었습니다.

AI는 코드를 쓰고, 문서를 갱신하고, 테스트를 돌리고, 커밋까지 만들 수 있습니다. 하지만 책임을 대신 져 주지는 않습니다. 그래서 AI를 믿는 가장 좋은 방법은 믿음이 아니라 제약, 문서, 검증을 촘촘히 만드는 것이었습니다.

긴 글 읽어주셔서 감사합니다. 비슷하게 AI 주도 개발 환경을 만들고 계신 분들이 있다면, 프롬프트보다 먼저 AI가 반복해서 안전하게 일할 수 있는 구조를 한번 점검해보셔도 좋겠습니다.

INSIK HWANG
BAS KOREA · Frontend Engineer