지난주 r/codex의 누군가가 더 이상 물어볼 필요가 없는 질문을 던졌습니다: "전문적인 AI 빌더처럼 Codex를 사용하는 방법은 무엇인가요?" 도구들은 이미 마법의 단계를 넘어선 지 1년이 지났습니다. 모델들은 "로그인 페이지를 만들어줘"라고 하면 실제로 로그인 페이지를 만들어낼 정도로 충분히 훌륭합니다. 그럼에도 불구하고 가장 많은 추천을 받은 답변은 영리한 프롬프트(Prompt)나 비밀 설정이 아니었습니다. 그것은 분명히 시행착오를 겪어본 누군가가 직접 조립한 워크플로우(Workflow)였습니다: 먼저 명세(Spec)를 작성하고, 이를 단계별 계획으로 나누며, 각 단계에 완료 정의(Definition of Done)를 부여하고, 코드를 짜기 전에 계획을 세운 뒤, 리드 엔지니어처럼 차이점(Diffs)을 검토하는 것입니다.

다시 한번 읽어보세요. "전문가들은 이 AI 도구를 어떻게 사용하는가"에 대한 최고의 답변은 AI 도구 자체에 관한 것이 아니었습니다. 그것은 AI를 활용하여 작업하기 위한 프로세스(Process)에 관한 것이었습니다. 에이전트(Agent)를 사용하여 실제 결과물을 출시하는 가장 빠른 방법은, 역설적이게도 에이전트와 아무런 관련이 없는 소프트웨어 개발의 영역이었습니다. 이것이 이 글 전체가 기반하고 있는 모순이며, 여러분이 올해 배울 수 있는 가장 유용한 사실입니다: 실제로 결과물을 만들어내는 AI 코딩 워크플로우는 대부분 AI 주변에 구축하는 워크플로우라는 점입니다.

모두가 계속해서 재발명하고 있는 워크플로우

여기에 수천 명의 빌더들이 각기 조금씩 다른 방식으로 수천 번씩 직접 다시 만들고 있는 뼈대가 있습니다:

flowchart LR
  A[Idea] --> B[Spec: 완료의 의미]
  B --> C[Plan: 단계별 분할]
...

형태 자체는 흥미로운 부분이 아닙니다. 흥미로운 부분은 '어느 단계가 작업을 수행하느냐'입니다. 대부분의 사람들은 "Build" 박스, 즉 에이전트가 마법이 일어나는 곳이라고 가정합니다. 왜냐하면 그 박스가 천 배는 더 좋아졌기 때문입니다. 하지만 그들은 틀렸으며, 여러분은 스스로 이를 증명할 수 있습니다. 강력한 에이전트에게 모호한 아이디어를 줘보십시오. 그러면 자신감 있고 그럴듯해 보이지만 틀린 결과물을 얻게 될 것입니다. 이제 평범한 에이전트에게 명확한 완료 정의가 포함된 정밀한 명세(Spec)를 줘보십시오. 그러면 실제로 출시할 수 있는 무언가를 얻게 될 것입니다. 힘은 모델에 있는 것이 아닙니다. "완료의 의미"라고 표시된 박스에 있으며, 그 박스는 어떤 도구도 여러분을 대신해 작성해주지 않는 바로 그 박스입니다.

하나의 기능, 시작부터 끝까지

추상화(Abstractions)는 고개를 끄덕이며 동의하기에는 쉽지만, 막상 구축을 위해 자리에 앉으면 무용지물이 됩니다. 그러니 실제 기능 하나를 루프(loop)를 통해 따라가 봅시다. 모든 앱에 필요하지만 아무도 작성하고 싶어 하지 않는 종류의 기능인 '비밀번호 재설정 흐름(password reset flow)'을 예로 들어보겠습니다.

아마추어 버전은 단 한 문장입니다. "비밀번호 재설정 기능을 추가해줘." 여러분은 이 문장을 에이전트(agent)에 붙여넣고, 에이전트가 6개의 파일에 걸쳐 400줄의 코드를 생성하는 것을 지켜봅니다. 그리고 미리보기(preview)에 양식이 나타나는 것을 보고, 완료된 것처럼 보이니까 머지(merge)해 버립니다. 3일 후, 한 사용자가 재설정 링크가 두 번 작동하거나, 만료되지 않거나, 이메일에 플러스(+) 기호가 있는 사람에게는 조용히 실패한다는 이메일을 보냅니다. 데모는 작동했습니다. 하지만 기능은 작동하지 않았습니다. 여러분은 격차(gap)를 배포한 것입니다.

이제 r/codex 댓글 작성자가 설명했던 버전을 보겠습니다. 코드를 작성하기 전에, 사람이 확인할 수 있는 조건들로 '완료(done)'가 실제로 무엇을 의미하는지 적습니다:

사용자가 이메일을 통해 재설정을 요청합니다. 30분 후에 만료되고 정확히 한 번만 작동하는 일회용 링크가 전송됩니다. 유효하지 않거나 만료된 링크는 크래시(crash)가 아닌 명확한 오류를 표시합니다. 재설정에 성공한 후에는 모든 기존 세션이 로그아웃됩니다. 알 수 없는 이메일 주소는 알려진 주소와 동일한 중립적인 확인 메시지를 반환하여, 양식이 계정 보유자를 찾아내는 데 사용될 수 없도록 합니다.

이것은 5가지의 테스트 가능한 조건이며, 방금 무슨 일이 일어났는지 주목하십시오. 여러분은 코드를 작성하지 않았습니다. 작성할 필요도 없었습니다. 하지만 여러분은 단 한 문장 버전에는 결코 없었던 것을 갖게 되었습니다. 바로 여러분의 머릿속 밖에 존재하며, 에이전트가 이를 기준으로 구축할 수 있고, 여러분이 생성된 코드의 한 줄도 읽을 수 없더라도 나중에 그 결과를 대조하여 확인할 수 있는 '완료의 정의(definition of done)'입니다. 명세(spec)가 결과물(deliverable)입니다. 코드는 그 하류(downstream)에 있을 뿐입니다.

그 지점부터 나머지 루프(loop)가 발을 디딜 곳이 생깁니다. 작업을 단계별로 나누고, 에이전트(agent)를 구축하러 보내면, 풀 리퀘스트(pull request)가 돌아왔을 때 자신이 자격이 없다고 느끼며 차이점(diff)을 멍하니 바라보고 있지 않게 됩니다. 당신은 다섯 가지 조건을 검토합니다. 리셋을 요청하고, 링크를 두 번 클릭하고, 두 번째 클릭이 실패하는 것을 지켜봅니다. 31분을 기다린 뒤, 링크가 죽었음을 확인합니다. 존재하지 않는 이메일을 입력하고, 메시지가 아무런 정보도 제공하지 않는지 확인합니다. 당신은 자신이 작성한 체크리스트에 따라 동작을 검토하고 있는 것이며, 이것이 바로 엔지니어가 아닌 사람도 충분히 수행할 수 있는 검토의 종류입니다. 우리는 코드를 읽을 수 없을 때 풀 리퀘스트를 검토하는 방법에서 이 기술을 심도 있게 다루었습니다. 여기서 핵심은 체크리스트가 있어야만 검토 자체가 가능하다는 점입니다.

명세(spec)가 곧 워크플로우인 이유

진지하게 받아들일 만한 반발이 존재합니다. 최근 Hacker News 스레드의 날카로운 댓글은 에이전트 워크플로우(agentic-workflow) 패러다임 전체를 "사람들이 토큰 소비량을 10배로 늘리도록 유도하기 위해 AI 기업들이 밀어붙이는 서사적 트렌드"라고 불렀습니다. 그 비판가는 절반은 맞았고, 그가 맞은 그 절반이 가장 중요한 부분입니다. 완료 정의(definition of done)가 없는 루프는 그들이 묘사한 그대로입니다. 즉, 계속해서 주사위를 던지게 만드는 값비싼 방법일 뿐입니다. 당신은 프롬프트(prompt)를 입력하고, 에이전트는 생성하며, 당신은 눈을 가늘게 뜨고 바라보다가 마음에 들지 않으면 다시 프롬프트를 입력합니다. 그리고 매 턴마다 크레딧(credits)을 소모하지만, 루프가 수렴할 대상이 없기 때문에 결국 아무것도 얻지 못한 채 헤매게 됩니다.

그 슬롯머신을 워크플로우로 바꾸는 것은 회의론자들이 결코 언급하지 않는 단 하나의 요소입니다. 더 나은 모델도 아니고, 더 높은 자율성도 아닙니다. 바로 출력을 측정할 수 있는 기준이 되는 명세(spec)입니다. 명세가 있으면 모든 루프 반복(iteration)은 목표와 정지 조건(stopping condition)을 갖게 됩니다. 증거가 명세와 일치할 때가 바로 '완료'입니다. 명세가 없다면, '완료'는 그저 당신이 레버를 당기는 것에 지쳤을 때가 될 뿐입니다. 완료 정의(definition of done)는 워크플로우에서 있으면 좋은 부가적인 단계가 아닙니다. 그것이 바로 워크플로우 그 자체입니다. 그 외의 모든 것은 배관(plumbing) 작업에 불과합니다.

이것이 바로 모델이 발전한다고 해서 워크플로우가 더 쉬워지지 않는 이유이며, 사람들이 놀라는 지점이기도 합니다. 더 유능한 에이전트(Agent)는 턴(turn)당 더 많은 결정을 내리며, 당신이 기록하지 않은 모든 결정은 에이전트가 당신을 대신해 나중에 발견하게 될 어떤 방향으로 조용히 내리는 결정이 됩니다. 에이전트가 스스로 할 수 있는 일이 많아질수록, 작성된 명세서(spec)는 에이전트의 속도와 당신의 주말 사이에 놓인 유일한 방어선이 됩니다. 어려운 부분은 계획(planning) 단계에서 멀어지는 것이 아니라, 오히려 계획 단계로 이동합니다.

이 과정이 수동 작업(hand-rolled process)을 벗어나는 지점

당신은 포스트잇과 절제력만으로 이 전체 루프를 직접 실행할 수 있으며, 실제로 많은 훌륭한 빌더(builder)들이 그렇게 하고 있습니다. 하지만 당신이 실제로 수동으로 유지 관리하고 있는 것들을 살펴보십시오. 모든 기능에 대한 완료 정의(definition of done), 이를 구축 가능한 단계로 나누는 방법, 어떤 조건이 확인되었고 어떤 조건이 확인되지 않았는지에 대한 기록, 그리고 한 세션에서 다음 세션으로 이어지는 이 제품이 무엇을 해야 하는지에 대한 기억입니다. 이것은 실제 작업이며, 당신이 혼자이든 50명의 팀이든 동일한 작업입니다. Reddit 댓글에서 이 주제가 계속해서 재발명되는 이유는 아무도 이것을 하나의 제품(product)으로 출시하지 않기 때문입니다.

그 간극을 메우는 것이 바로 BrainGrid입니다. 사용자가 평이한 언어로 기능을 설명하면, Planning Agent (기획 에이전트)가 이를 명시적인 수락 기준 (acceptance criteria)을 갖춘 요구사항으로 변환합니다. 이 과정에서 코드가 존재하기도 전에 만료된 링크나 플러스 기호 이메일 케이스와 같은 문제들을 잡아낼 수 있도록, 사용자가 미처 생각하지 못한 명확화 질문 (clarifying questions)을 던집니다. 그다음 Builder Agent (빌드 에이전트)가 해당 명세 (spec)를 바탕으로 작업을 수행하는데, 실시간 미리보기가 가능한 관리형 클라우드 샌드박스 (managed cloud sandbox) 환경에서 작업하거나, Claude Code, Cursor, 또는 Codex를 사용하여 사용자의 GitHub 리포지토리에서 직접 작업합니다. 작업이 완료되면, 검증 (verification) 단계에서 모든 수락 기준에 따라 결과를 확인하므로, 풀 리퀘스트 (pull request)는 사용자가 직접 해석해야 하는 디프 (diff) 대신 증거가 첨부된 상태로 전달됩니다. 이것이 바로 Plan (계획), Build (빌드), Verify (검증), Repeat (반복)로 이어지는 전체 루프이며, 실제로 작업을 수행하고 '완료의 정의 (definition of done)'를 포착하는 이 부분은 제품이 기억하는 영역이기에, 프로젝트마다 매번 다시 구축할 필요가 없습니다. 저희는 BrainGrid 방식으로 구축하기에서 계획 단계의 절반을 심도 있게 다루며, AI 에이전트가 검증할 수 있는 수락 기준 작성법에서 명세 작성 기술 자체를 다룹니다.

솔직한 한계점은 다음과 같습니다: 명세 (spec)는 스스로 작성되지 않으며, 잘못된 명세는 매우 확신에 찬 상태로 잘못된 기능을 배포합니다. 만약 잘못된 조건을 작성한다면, 에이전트는 그 조건들을 완벽하게 충족할 것이고, 당신은 정확하게 잘못된 것을 만들게 될 것입니다. 이 워크플로우 (workflow)가 '무엇이 좋은 결과물인가'에 대한 당신의 판단을 제거하는 것은 아닙니다. 다만 그 판단이 머지 (merge) 버튼을 누를 때 결과를 비교하는 모호한 느낌으로 남는 대신, 빌드를 실제로 조종할 수 있도록 초기에 단 한 번 기록되도록 보장할 뿐입니다.

따라서 다음에 전문가들이 최신 에이전트 (Agent)를 어떻게 사용하는지 궁금해질 때, 전문가들이 실제로 답변했던 내용을 기억하십시오. 그들은 프롬프트 (Prompt)를 공유한 것이 아닙니다. 그들은 워크플로우 (Workflow)를 공유했으며, 그 중심에는 가장 화려하지 않은 단계가 있었습니다. 빌드하기 전에 무엇이 '완료 (Done)'인지 기록하십시오. 에이전트는 빨라졌습니다. 하지만 무엇을 완료된 것으로 간주할지 결정하는 것은 여전히 당신의 몫이며, 그것이 바로 결과물을 출시 (Ship)하게 만드는 유일한 작업입니다.

FAQ

AI 코딩 워크플로우 (AI coding workflow)란 무엇인가요?

AI 코딩 워크플로우란 단순히 에이전트에게 프롬프트를 입력하고 요행을 바라는 것이 아니라, 아이디어를 출시 가능한 소프트웨어로 바꾸기 위해 AI 에이전트 주변에 구축하는 반복 가능한 프로세스를 의미합니다. 실제로 이는 일관된 형태로 수렴되었습니다: 무엇이 "완료"인지를 정의하는 명세 (Spec)를 작성하고, 작업을 단계별로 나누며, 에이전트가 해당 명세에 따라 빌드하도록 하고, 머지 (Merge)하기 전에 원래의 조건과 대조하여 결과를 검증하는 것입니다. 에이전트는 코드 생성 (Code generation)을 담당하고, 워크플로우는 코드 생성이 올바른 목표를 향하도록 만드는 모든 것을 담당합니다. 가장 흔한 실수는 명세가 실제로 작업을 수행하는 부분임에도 불구하고, 프롬프트를 워크플로우로 취급하는 것입니다.

AI 코딩 워크플로우를 어떻게 설정하나요?

모두가 건너뛰는 단계부터 시작하십시오: 코드를 작성하기 전에, 한 줄짜리 프롬프트가 아니라 사람이 확인할 수 있는 짧은 조건 목록으로서 '완료'된 상태가 어떤 모습인지 작성하십시오. 그런 다음 기능을 한 번에 하나씩 검토할 수 있을 만큼 작은 단계로 나누고, 각 단계를 에이전트에게 전달하십시오. 에이전트가 결과를 반환하면, 디프 (Diff)를 읽는 대신 실행 중인 결과가 작성한 조건에 부합하는지 확인하십시오. 이 제품이 무엇을 해야 하는지에 대한 기록을 유지하여, 매 새로운 세션이 제로 베이스에서 시작되지 않도록 하십시오. 이를 메모와 절제력을 통해 수동으로 수행할 수도 있고, 명세를 캡처하고, 이를 바탕으로 빌드를 실행하며, 결과를 대신 검증해 주는 도구를 사용할 수도 있습니다.

AI 모델이 충분히 뛰어나다면 계획이 정말 필요한가요?

네, 그리고 직관과는 반대로 모델이 발전할수록 계획은 더 중요해집니다. 더 유능한 에이전트(Agent)는 턴(Turn)당 더 많은 결정을 내리며, 당신이 명시하지 않은 모든 결정은 에이전트가 스스로 내리는 결정이며, 이는 사후에야 당신이 발견하게 될 방향으로 흐르게 됩니다. 모호한 요청을 받은 강력한 모델은 확신에 차 있고 그럴듯하지만 틀린 결과를 만들어내고, 명확한 완료 정의(Definition of Done)가 주어진 평범한 모델은 실제로 배포 가능한 결과물을 만들어냅니다. 결과의 성패를 결정짓는 작업은 스펙(Spec)에 달려 있습니다. 왜냐하면 그것이 에이전트의 속도가 지향해야 할 유일한 목표이기 때문입니다. 계획을 건너뛰는 것은 루프(Loop)를 주사위를 계속 던지는 값비싼 방식으로 만드는 길입니다.

코드를 읽을 줄 모른다면 AI 풀 리퀘스트(Pull Request)를 어떻게 리뷰하나요?

구문(Syntax)이 아니라 동작(Behavior)을 리뷰하세요. 요약(Summary)을 읽고 범위(Scope)가 요청한 내용과 일치하는지 확인한 다음, 프리뷰(Preview)를 열고 실제 사용자처럼 수락 기준(Acceptance Criteria)을 따라가며 검증하세요. 여기에는 만료된 링크, 잘못된 입력, 빈 양식과 같은 실패 케이스(Failure cases)도 포함되어야 합니다. 얼마나 많은 파일이 변경되었는지 확인하고, 작은 변경보다는 광범위하게 퍼져 있는 변경에 대해 더 주의를 기울이세요. 실행 중인 기능이 사전에 작성한 모든 조건을 충족할 때만 승인하세요. 이것이 작동하는 이유는 빌드 전에 완료(Done)를 정의했기 때문이며, 따라서 리뷰는 모호한 기억에 의존해 추측하는 대신 목록을 체크하는 과정이 됩니다.

바이브 코딩(Vibe coding)과 AI 코딩 워크플로우(AI coding workflow)의 차이점은 무엇인가요?

바이브 코딩(Vibe coding)은 작성된 완료 정의(Definition of Done)도 없고 검증할 대상도 없이 '프롬프트 입력, 생성, 눈으로 확인, 반복'하는 방식입니다. 이는 프로토타입을 만들거나 앱의 중요도가 낮을 때 숨겨진 격차를 빠르게 배포하는 데는 훌륭합니다. 반면 AI 코딩 워크플로우(AI coding workflow)는 누락된 조각, 즉 출력을 측정할 기준이 되는 스펙(Spec)을 추가하여 각 반복(Iteration)이 목표와 명확한 종료 조건(Stopping condition)을 갖게 합니다. 차이점은 모델이 얼마나 좋은지 또는 얼마나 빠른지가 아닙니다. 루프 안에 "아직 아님"이라고 말할 수 있는 무언가가 있느냐의 여부이며, 이것이 바로 생성을 배포로 바꾸는 핵심입니다.

BrainGrid는 당신의 아이디어를 수용 기준 (Acceptance Criteria)으로 변환하고, 당신이 선택한 에이전트 (Agent)를 통해 이를 바탕으로 빌드하며, 모든 변경 사항을 증거와 함께 검증합니다. 따라서 당신이 매번 수동으로 재구축하던 워크플로우는 이제 단순한 제품이 됩니다. braingrid.ai에서 직접 체험해 보세요.

원문은 BrainGrid 블로그에 게시되었습니다.