subflow 만들기 ① — AI 를 예측 가능하게 만드는 가장 작은 단위

subflow 만들기 시리즈 ① AI 를 예측 가능하게 만드는 가장 작은 단위 (이 글) · ② 사고 한 건에서 계약 한 줄까지 · ③ 갈라지고, 틀리고, 흐름이 되기까지

이 시리즈가 왜 시작됐는지는 셋이 남았을 때 — 우리 팀이 비즈니스 플로우에 정착하기까지 에 있습니다.

한 줄로

subflow 는 설계해서 만든 적이 없습니다. 실제 작업이 돌다가 «이 일을 맡을 단계가 없어서» 사고가 나면, 그 자리에 이름을 붙이고 계약을 써서 끼워 넣었습니다. 지금 있는 25개가 모두 그렇게 생겼습니다.

이 시리즈는 그 과정을 세 편에 나눠 정리합니다. 첫 편은 subflow 가 무엇인지, 그리고 왜 가장 아래에서부터 정의했는지입니다.

왜 가장 작은 단위부터였나

AI 에이전트와 일을 시작했을 때 속도보다 예측할 수 없다는 점이 가장 큰 문제였습니다. 같은 요청에도 세션마다 결과의 모양이 달랐습니다.

그래서 거꾸로 생각했습니다. 큰 흐름을 먼저 그리지 않고 AI 의 행동을 예측할 수 있는 가장 작은 단위부터 정의하기로 했습니다.

AI 를 많이 다뤄 보지 않은 상태라면, AI 의 행동을 예측할 수 있도록 subflow 부터 정의한다.

입력과 산출이 정해진 단계는 누가 돌려도 같은 모양으로 움직였습니다. 그 단계 하나가 subflow 입니다.

세 개의 층 — «모르는 것» 이 층을 정한다

subflow 는 세 층 구조의 맨 아래에 있습니다.

Supervisor   여러 흐름을 찾고, 계속할지 멈출지 판정한다
    │ 호출 ↓        ↑ 보고서
Root         단계 순서를 조율한다 (= 비즈니스 플로우, rootflow)
    │ 입력 ↓        ↑ 산출
Sub          자기 단계 하나를 수행한다 (= subflow)

층을 나눈 기준은 «무엇을 하나» 가 아니라 «무엇을 모르나» 입니다.

층	하는 일	모르는 것
Supervisor	여러 흐름을 찾고 판정한다	흐름의 내부 — 보고서만 본다
Root (rootflow)	단계 순서를 조율하고 경계를 확인한다	각 단계의 방법 — 계약으로만 잇는다
Sub (subflow)	자기 단계 하나를 수행한다	전체 순서, 다른 단계의 방법

힘은 각 층이 모르는 것이 분명한 데서 나옵니다. rootflow 는 조사 단계가 어떻게 조사하는지 몰라도 됩니다. 조사 단계가 무엇을 받아서 무엇을 내놓는지만 알면 됩니다.

이 정의도 한 번 바뀌었습니다. 처음에는 맨 아래 층을 «한 건의 작업»으로 두었는데, 그러면 단계 하나가 설 자리가 없었습니다. 그래서 «비즈니스 플로우 = Root 층, 그 안의 각 단계 = subflow» 로 고쳤습니다.

subflow 의 계약

rootflow 는 subflow 의 방법을 모르고, 계약만 보고 단계를 잇습니다. 계약에는 이런 항목이 있습니다.

항목	뜻
① 입력	어느 subflow 의 어떤 산출을 받는가
② 방법	subflow 가 스스로 갖는다 (rootflow 는 모른다)
③ 산출	어떤 파일을 내놓는가 + 무엇을 어떤 축으로 셌나
④ 통과 체크	입력을 빠짐없이 소비했나
⑤ 결정 반출	이 단계에서 나온 결정을 결정 대장 한 곳으로 넘긴다
⑥ 실패 반송지	틀렸다면 어디로 돌아가나 — 틀린 판정을 처음 만든 subflow
⑦ 진입 조문 · ⑧ 종료 증명	들어갈 때 규칙을 읽고, 나올 때 거짓이 없음을 증명한다

이 중 단계와 단계 사이의 경계에 해당하는 다섯 항목(①③④⑤⑥)은 계약 표에 열로 적힙니다. 방법(②)은 표에 없습니다. 각 subflow 가 스스로 가집니다.

몇 가지 말도 함께 고정했습니다.

말	뜻
target	이 작업이 소유하는 대상(모듈·폴더). 두 작업이 같은 대상을 만지면 위반
결정 대장	어느 단계에서 나온 결정이든 한 파일에 모은다
보고서	계획서 안의 «Report» 절 — 위층이 읽는 유일한 입력

실제 조문은 이렇게 생겼습니다

안드로이드 저장소의 실제 헌법에서 계약 표의 머리 문장과 세 행을 옮겼습니다. 결정 반출 칸과 내부 참조는 생략했습니다.

②방법은 아래 각 절이 소유한다. 이 표는 경계(①③④⑤⑥)만 고정한다 — rootflow 는 방법을 모르고 이것만 보고 잇는다.

subflow	① 입력	③ 산출 + 셈의 축	④ 통과 체크	⑥ 실패 반송지
survey/ui	대상 · 작업 종류 · 근거 자료 — 다른 축 산출 금지	요구 표면 · 축: 화면 N · 핸들러 M	«도메인(module) 표면을 mock 하면 화면 로직이 테스트되는가» · 위반 ↔ 규칙 절 제목 매칭	— (첫 subflow). 입력 부족은 사용자에게
join/viewmodel	survey/ui + survey/domain 양쪽 산출	요구 ↔ 제공 대조표 · 축: 요구 N ↔ 제공 M · 불일치 K	불일치 전건 처분 (충돌은 한쪽 채택 금지)	그 표면을 처음 주장한 축
plan	sdd 항목 전부	매핑표 · 슬라이스 · 축: SDD 항목 N ↔ 매핑 N	1:1 (빠짐 0) · 슬라이스마다 독립 게이트 가능	sdd

반송지에는 따로 귀속 규칙이 붙어 있습니다.

반송지 = 틀린 판정을 만든 subflow. 검수한 곳도, 발견된 곳도 아니다.

1. 발견마다 «이 판정을 처음 만든 subflow 가 어디인가» 를 적는다. 그게 반송지다.
2. 후보가 둘 이상이면 가장 이른 subflow 로 보낸다 (뒤는 앞의 산출을 소비하므로 앞이 틀리면 뒤도 틀린다).
3. 계약 자체가 틀린 경우는 실행 단계가 아니라 그 계약의 소유 subflow 로 간다.

표 한 줄이 곧 AI 에게 주는 지시입니다. «무엇을 받고, 무엇을 몇 개 세어 내놓고, 무엇으로 통과를 확인하고, 틀리면 어디로 돌아가는가» 가 한 줄에 다 있습니다.

③ 산출에 «무엇을 어떤 축으로 셌나» 가 들어간 이유

산출 칸에 파일 이름만 적지 않고 세는 축까지 적게 한 데는 계기가 있습니다. 조사 단계에서 같은 조사를 두 번 했는데, 두 번 다 축이 틀렸습니다. 셋으로 갈라 세야 할 파일 22개를 한 덩어리로 센 것입니다. 무엇을 셌는지가 산출에 남아 있지 않으니, 틀린 것을 아무도 알아채지 못했습니다.

⑥ 반송지가 «처음 만든 곳» 인 이유

실패를 바로 앞 단계로 돌려보내면, 틀린 판정이 시작된 곳은 그대로 남습니다. 그래서 반송지는 언제나 그 판정을 처음 만든 subflow 입니다. 2편에서 볼 rework 가 이 반송을 맡습니다.

위는 틀만, 나머지는 아래에서

정의할 때의 원칙은 하나입니다.

층	무엇을 정의하나
아래 (subflow)	구체적인 계약 — 입력, 산출, 통과 체크, 반송지. 행동이 예측 가능해지는 곳
위 (Root · Supervisor)	계약 표, 완료 기준, 보고서 형식 같은 템플릿 + 단계 순서 같은 추상적인 흐름

실제로 위에서 온 것은 3계층과 단계 순서라는 골격 하나뿐입니다. 이 골격은 다른 저장소(웹 어드민)에서 먼저 쓰던 것을 옮겨 왔습니다. 나머지는 전부 실제 작업에서 자랐습니다.

① 골격 (위에서 옴): 3계층 · 단계 순서
        ┆ 틀
② 첫 주행 — 실제 작업 한 건을 손으로 돌린다
③ 반복되는 자리에 이름을 붙여 subflow 로 — 계약 발견
④ subflow 세분화 — 10개에서 25개로
⑤ rootflow 규칙 — 멈추는 곳, 갈래
⑥ 집행 수단 — 기계가 세는 가드
⑦ Supervisor — 실물이 생긴 단계만

위에서 먼저 정의하려던 시도는 두 번 다 되돌렸습니다. Figma 화면 개발용 흐름을 따로 선언했다가 이틀 만에 기존 흐름의 갈래로 흡수했고 감독 문서를 먼저 썼다가 흐름이 아니라 관측 기록이 되어 버려 다시 썼습니다. 이 이야기는 3편에서 자세히 다룹니다.

지금 있는 subflow

8월 초 10개로 시작해 9월 중순 24개, 10월 초 25개가 됐습니다. 단계별로 묶으면 이렇습니다.

단계	subflow
조사	survey/entry · survey/ui · survey/domain · survey/infra (+ Figma 작업일 때 survey/figma)
조사 이음새	join/entry-ui · join/viewmodel · join/domain-infra
조사 정리	survey/ledger (조사 결과를 상태 × 이벤트 전이표 하나로)
Figma 갈래	disposition · cds-diff
설계	architecture · bdd · sdd
계획	plan · test-plan
판정 · 실행	gate · execute
검증	verify · verify/screen · verify/log
가로지르는 것	audit(독립 검수) · rework(반송) · resolve(규칙에 먼저 묻기) · sync(통합 브랜치 변경 재확인)

대부분은 «무엇 때문에 생겼는지» 가 결정 기록에 남아 있습니다. 기록이 없는 셋(test-plan · execute · bdd)도 숨기지 않고 «기록 없음» 으로 둡니다.

정리

• subflow 는 단계 하나의 계약입니다. 입력, 산출(세는 축 포함), 통과 체크, 결정 반출, 반송지를 정합니다.
• 층은 «무엇을 모르나» 로 정의합니다. rootflow 는 subflow 의 방법을 모르고 계약만 봅니다.
• 위는 틀만, 나머지는 아래에서. 실물이 먼저고 이름은 뒤입니다.

다음 편에서는 실제 사고 한 건이 subflow 하나가 되기까지, 만드는 절차 7단계를 사례 두 개로 따라가 보겠습니다.

② 사고 한 건에서 계약 한 줄까지 →