2026년의 실제 AI 개발 모습 - 프롬프팅을 멈추고 디렉팅을 시작하라

먼저 솔직하게 말씀드리고 싶은 것이 있습니다.
대부분의 "AI로 [무엇이든] 만들었습니다"라는 게시물들은 사실 "AI에게 프롬프트를 입력하고 결과물을 대충 수정했습니다"에 불과합니다. 그것은 워크플로우 (Workflow)가 아닙니다. 그것은 불필요한 단계가 추가된 즉흥 연주일 뿐입니다.

이 포스트는 구조화된 접근 방식에 관한 것입니다. 프론트엔드 (Frontend) 포트폴리오, 풀스택 (Full-stack) SaaS, REST API, 또는 마이크로서비스 (Microservice)를 구축하든 상관없이 동일하게 적용되는 방식입니다. 단계는 같고, 규율도 같으며, 결과도 같습니다.

현재 우리가 처한 상황

하지만 불편한 수치가 하나 있습니다. **개발자의 42%**가 AI가 생성한 코드가 디버깅 (Debugging)에 상당한 시간을 소비해야 하는 버그를 유발했다고 답했습니다. 또 다른 **38%**는 코드가 프로젝트의 컨벤션 (Conventions)과 일치하지 않는다고 답했습니다.

빠르지만 틀린 것. 이것이 대부분의 팀이 처한 현재의 AI 보조 개발 (AI-assisted development) 상태입니다.

문제는 도구가 아닙니다. 문제는 워크플로우 (Workflow), 즉 워크플로우의 부재입니다.

진짜 문제 - AI는 모든 것을 잊어버린다

새 채팅창을 엽니다. 에러를 붙여넣습니다. 해결책을 얻습니다. 그것을 다시 복사합니다.

내일 또 다른 채팅창을 엽니다. 프로젝트 전체를 다시 설명합니다. 또 다른 에러를 붙여넣습니다. 또 다른 해결책을 얻습니다.

모든 세션은 제로(Zero)에서 시작됩니다. AI는 당신의 폴더 구조, 명명 규칙 (Naming conventions), 디자인 토큰 (Design tokens), API 패턴 (API patterns)에 대한 기억이 없습니다. 당신은 개발하는 시간의 절반을 컨텍스트 (Context)를 제공하는 데 허비하게 됩니다.

이것이 바로 채팅창의 함정입니다. AI를 사용하는 것처럼 느껴지지만, 실제로는 그저 더 느린 Stack Overflow일 뿐입니다.

단 하나의 명령어를 작성하기 전에 - 디자인 기반 (Design Foundation)

이 단계는 터미널 (Terminal)을 열기 전에 이루어집니다. 이것이 다른 모든 것을 작동하게 만드는 핵심입니다.

디자인의 스크린샷을 찍으세요. Figma, Adobe XD, Canva, PDF 목업 (Mockup) 등 무엇이든 상관없습니다. 기능별, 페이지별, 상태별로 스크린샷을 내보내세요. 특정 컴포넌트 (Component)의 근접 스크린샷, 레이아웃 (Layout)을 위한 전체 스크린샷, 라이트 모드 (Light mode)와 다크 모드 (Dark mode) 모두 준비하세요.

다음과 같이 정리하세요:

docs/
└── designs/
    ├── system-design.md     ← 모든 디자인 토큰 (Design tokens)
...

system-design.md를 작성하세요. 모든 색상 토큰(color token)과 그 헥스 값(hex value), 모든 글꼴 패밀리(font family), 글꼴 크기(font size), 글꼴 두께(font weight), 모든 간격 값(spacing value), 모든 테두리 반경(border radius)을 포함해야 합니다. 라이트 모드(Light mode)와 다크 모드(Dark mode)를 각각 별도로 작성하세요.

## Colors
--color-bg-page:      #f7f7f2   (light) / #0d0d0d (dark)
--color-text-primary: #111111   (light) / #f0f0f0 (dark)
...

이 파일은 AI가 당신의 시각적 언어(visual language)를 이해하기 위해 읽는 문서입니다. 이 파일이 없다면 AI는 추측을 하게 됩니다. 이 파일이 있다면 모든 컴포넌트(component)가 당신의 정확한 토큰(tokens)을 사용하게 됩니다.

CLAUDE.md를 작성하세요. 프로젝트의 성서(bible)입니다. 기술 스택(Tech stack), 폴더 구조(folder structure), 명명 규칙(naming conventions), AI가 따라야 할 모든 규칙을 담습니다. 이것은 한 번만 작성하면 됩니다. AI는 매 세션(session)마다 이를 읽으며 절대 잊지 않습니다.

CONTEXT.md를 작성하세요. 도메인 언어(domain language)입니다. 당신의 프로젝트에서 사물들은 실제로 무엇이라 불립니까? User와 Consultant의 차이는 무엇입니까? assign과 link의 의미 차이는 무엇입니까? 용어(terminology)가 문서화되면, AI는 자신이 다루는 모든 파일에서 이를 일관되게 사용합니다.

스크린샷, system-design.md, CLAUDE.md, CONTEXT.md라는 이 네 가지 요소가 갖춰지면, AI는 당신의 프로젝트에 대한 영구적인 기억을 갖게 됩니다. 더 이상 매 세션마다 처음부터 다시 설명할 필요가 없습니다.

4단계 루프 (The Four-Phase Loop)

네 번의 강력한 정지 지점(hard stops)이 있습니다. 현재 단계가 완료될 때까지 아무것도 앞으로 나아가지 않습니다. 이 정지 지점들은 관료주의가 아니라, 이 프로세스의 핵심 목적입니다.

1단계 - 그릴링 (Phase 1 - Grilling)

트리거(Triggered by): /grill-with-docs build <feature>

AI는 당신의 모든 문서(system-design.md, CLAUDE.md, CONTEXT.md, 관련 스크린샷)를 읽은 다음, 해당 기능(feature)에 대해 당신을 심문(interrogates)합니다. 한 번에 하나씩 질문합니다. AI는 다음 질문을 하기 전에 당신의 답변을 기다립니다.

프론트엔드(frontend) 기능의 경우:
헤딩(heading)의 글꼴 크기는 무엇인가요? 호버(hover) 시에는 어떤 일이 일어나나요? 빈 상태(empty state)는 어떻게 보이나요? 이것은 어떤 스크린샷과 일치하나요?

백엔드 기능(backend feature)의 경우:
요청 본문(request body)은 어떤 모습인가요? 유효성 검사 오류(validation error) 시 어떤 HTTP 상태 코드(HTTP status)를 반환하나요? 이 엔드포인트(endpoint)는 인증(authenticated)이 필요한가요? 외래 키(foreign key)가 존재하지 않으면 어떤 일이 발생하나요?

풀스택 기능(full-stack feature)의 경우:
프론트엔드(frontend)와 백엔드(backend) 사이의 API 계약(API contract)은 무엇인가요? 에러 핸들링(error handling)의 주체는 누구인가요? 요청이 대기 중(pending)일 때 프론트엔드는 무엇을 보여주나요? 요청이 실패했을 때는요?

여기서 답변된 모든 질문은 3단계(Phase 3)에서 작성되지 않을 버그(bug)입니다. 이 단계는 docs/tasks/<feature>.md에 작업 명세서(task spec file)가 작성되면 종료됩니다. 그 후에는 엄격한 중단(hard stop)이 이루어집니다. 코드 작성은 없으며, src/ 디렉토리 내에 아무것도 남기지 않습니다.

_"1단계(Phase 1)에서 답변된 모든 질문은 3단계(Phase 3)에서 작성되지 않을 버그입니다."

2단계 - PRD

트리거(Triggered by): /prd 또는 /to-prd

AI는 질의응답(grilling session)에서 나온 모든 내용을 종합하여 제품 요구사항 문서(Product Requirements Document, PRD)를 작성합니다. 문제 정의(problem statement), 사용자 스토리(user stories), 구현 결정 사항(implementation decisions), API 계약(API contracts), 데이터 형태(data shapes), 명시적으로 범위에서 제외된 사항(out of scope) 등이 포함됩니다.

사용자가 이를 검토합니다. 잘못된 부분이 있다면 표시(flag)하고, 일치한다면 그렇게 말합니다. 그 후 다시 엄격한 중단(hard stop)이 이루어집니다.

GitHub MCP가 연결된 경우, PRD는 자동으로 GitHub 이슈(issue)로 제출됩니다. 단 한 줄의 코드도 작성되기 전에 모든 기능은 추적 가능한 이슈가 됩니다.

# GitHub MCP를 한 번만 연결하세요
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_TOKEN"

이제 /prd를 실행하면 명세서가 생성되고 이슈가 열립니다. 3단계(Phase 3)가 완료되면, AI는 해당 이슈와 연결된 PR(Pull Request)을 자동으로 생성합니다. 명세(spec), 구현(implementation), 검토(review), 병합(merge)에 이르는 전체 기능 라이프사이클(feature lifecycle)이 터미널을 떠나지 않고도 GitHub에서 추적됩니다.

3단계 - TDD

트리거(Triggered by): /tdd build <feature>

모든 코드는 여기서 작성됩니다. 사이클은 red → green → refactor(실패 → 성공 → 리팩터링)로 진행됩니다. 실패하는 테스트를 작성하고, 이를 통과하기 위한 최소한의 코드를 작성한 뒤, 정리(clean up)하고 다음 동작으로 넘어갑니다.

프론트엔드 컴포넌트의 경우:
타입(Types)을 먼저 정의하고, 그다음 데이터(Data), 컴포넌트(Component), 그리고 페이지에 연결(Wired into the page)하는 순서로 진행됩니다. 빌드가 통과되면, Playwright MCP가 자동으로 브라우저를 열어 스크린샷을 찍고, 이를 디자인 참조(Design reference)와 비교하여 모든 불일치 사항을 나열한 뒤, 이를 수정하고 다시 스크린샷을 찍습니다. 라이트 모드(Light mode)와 다크 모드(Dark mode) 모두 일치할 때까지 이 과정을 반복합니다.

백엔드 엔드포인트(Backend endpoint)의 경우:
타입(Types)을 먼저 정의하고, 그다음 서비스 로직(Service logic), 컨트롤러(Controller), 그리고 라우트 등록(Route registration) 순으로 진행됩니다. 테스트는 해피 패스(Happy path), 유효성 검사 오류(Validation errors), 인증 실패(Authentication failures), 그리고 제품 요구 사항 문서(PRD)에 명시된 엣지 케이스(Edge cases)를 모두 다룹니다.

API 연동(API integration)의 경우:
모의 응답(Mocked responses)을 사용하여 서비스 레이어(Service layer)를 먼저 구축하고 테스트합니다. 그 후 실제 API를 연결합니다. 오류 상태(Error states), 로딩 상태(Loading states), 빈 상태(Empty states)가 모두 PRD와 일치하는지 검증합니다.

아직 아무것도 커밋(Commit)되지 않았습니다. 4단계가 먼저 실행됩니다.

4단계 - 리뷰 (Review)

트리거(Triggered by): /review

/tdd가 완료되면, AI는 방금 구축한 모든 것을 사용자의 CLAUDE.md 규칙에 따라 감사(Audit)합니다.

• 토큰(Tokens)으로 처리해야 할 하드코딩된 값(Hardcoded values)이 있는가? 플래그(Flagged) 처리.
• TypeScript 타입이 누락되었는가? 플래그 처리.
• 기존 프리미티브(Primitives)를 중복 사용하는 컴포넌트가 있는가? 플래그 처리.
• 오류 처리(Error handling)가 누락된 API 호출이 있는가? 플래그 처리.
• 접근성(Accessibility) 문제가 있는가? 플래그 처리.

그다음 AI는 플래그 처리된 모든 사항을 수정합니다. 여러분이 승인하는 디프(Diff)는 단순히 동작하는 코드가 아니라, 깔끔한 코드(Clean code)입니다.

/review를 통과하면, AI는 커밋 메시지(Commit message)를 제안하고 전체 디프(Full diff)를 보여주며 대기합니다. 사용자가 검토하고 승인하면 커밋을 수행하거나, GitHub 이슈(GitHub issue)와 연결된 PR(Pull Request)을 자동으로 생성합니다.

전체 설정 (The Full Setup)

전역(Globally) 1회 설치:

# Claude Code CLI
npm install -g @anthropic-ai/claude-code

...

프로젝트별 - 4개의 파일:

docs/designs/system-design.md   ← 디자인 토큰 (design tokens)
docs/designs/ss/*.png            ← 기능 스크린샷 (feature screenshots)
CLAUDE.md                        ← 프로젝트 규칙 (project rules)
...

기능별 - 4개의 명령어:

/grill-with-docs build <feature>   # 질문 + 작업 명세(Task spec) → 중단(STOP)
/prd                                # PRD + GitHub 이슈(GitHub issue)   → 중단(STOP)
/tdd build <feature>                # 빌드 + Playwright   → 중단(STOP)
...

엔드 투 엔드(End to End)의 실제 모습

# 사용자 관리 기능 구축

/grill-with-docs build user management
...

단 하나의 기능. 네 개의 명령어. 완전한 감사 추적(Audit trail). 예기치 못한 상황 없음.

강제 중단(Hard Stops)이 중요한 이유

대부분의 AI 보조 워크플로우(AI-assisted workflows)가 실패하는 이유는 AI가 계속해서 움직이기 때문입니다. 사용자가 무엇을 원하는지 파악하는 동안에도 AI는 코드를 생성합니다. 방향이 잘못되었다는 것을 깨달았을 때는 이미 되돌려야 할 상당한 양의 코드가 쌓여 있는 상태입니다.

'Grilling(심층 검토)' 이후에 중단을 강제한다는 것은 구현(Implementation) 전에 사양(Spec)을 확정한다는 것을 의미합니다. PRD(제품 요구사항 문서) 이후에 중단을 강제한다는 것은 코드가 실행되기 전에 계약(Contract)이 체결됨을 의미합니다. TDD(테스트 주도 개발) 이후에 중단을 강제한다는 것은 코드가 커밋(Commit)되기 전에 리뷰가 완료됨을 의미합니다.

4단계(Phase 4)에 도달하면 더 이상 미결된 질문은 없으며, 오직 깔끔한 실행에 대한 품질 검사(Quality check)만 남게 됩니다.

Playwright 시각적 검사는 프론트엔드(Frontend)의 품질 루프를 완성합니다. 테스트 스위트(Test suite)는 백엔드(Backend)의 품질 루프를 완성합니다. /review 단계는 코드 품질(Code quality)의 품질 루프를 완성합니다. 자동화된 검증(Automated verification)이 없다면 "괜찮아 보이네요"나 "작동하는 것 같네요"가 기준이 됩니다. 하지만 자동화된 검증이 있다면 검사는 객관적이고 반복 가능해집니다.

수치로 보는 현황

Gartner는 2028년까지 **기업 소프트웨어 엔지니어의 75%**가 매일 AI 코딩 어시스턴트(AI coding assistants)를 사용할 것이라고 예측했으며, 이는 2025년의 약 25%에서 크게 증가한 수치입니다. Anthropic의 2026년 개발자 보고서에 따르면 Claude Code 사용량은 전년 대비 340% 성장했습니다. 전문 개발자가 일상적인 워크플로우(Workflow)에서 AI를 사용하는 비율은 2026년 1분기에 처음으로 **60%**를 넘어섰습니다.

하지만 다가오는 변화는 단순히 더 많은 개발자가 AI를 사용하는 것에 관한 것이 아닙니다. 그것은 개발자들이 AI를 '다르게' 사용하는 것에 관한 것입니다. 즉, 임시방편적인 프롬프팅(Ad-hoc prompting)에서 구조화된 워크플로우(Structured workflows)로, 채팅창 대화에서 규율 있는 협업(Disciplined collaboration)으로 이동하는 것을 의미합니다.

4단계 루프는 그러한 구조의 한 가지 버전입니다. 구체적인 명령어는 진화할 것이고, 더 나은 도구들이 등장할 것입니다. 하지만 의사결정을 앞당기고(Front-load decisions), 사양을 확정하며(Lock the spec), 자동으로 검증하고(Verify automatically), 커밋하기 전에 리뷰하는(Review before committing) 근본적인 규율은 그대로 유지될 것입니다.

왜냐하면 그 규율은 AI에 관한 것이 아니기 때문입니다. 그것은 얼마나 좋은 소프트웨어가 구축되는가에 관한 것입니다. AI는 단지 실행(execution)을 더 빠르게 만들 뿐입니다.

솔직한 부분

이 워크플로우(workflow)는 당신이 날카로운 질문들에 답할 수 있을 때만 작동합니다. 1단계(Phase 1)는 당신의 사고 과정에 있는 모든 공백을 드러냅니다. 당신이 무엇을 만들고 있는지 모른다면, AI는 당신을 대신해 그것을 알아낼 수 없습니다.

AI는 사고(thinking)와 출시(shipping) 사이의 마찰을 제거합니다. 그것은 사고를 대체하지 않습니다.

우리는 코드를 작성하는 법을 배우기 위해 수년을 보냈습니다. 다음 기술은 코드를 디렉팅(directing)하는 법을 배우는 것입니다.

여기서 시작하세요

1. 현재 프로젝트 디자인의 스크린샷을 찍으세요
2. 토큰(tokens)을 추출하는 system-design.md를 작성하세요
3. CLAUDE.md를 작성하세요 - 10분 내외로, 기초적인 내용만 작성합니다
4. 다음 기능(feature) 개발 시 /grill-with-docs를 실행하세요
5. 모든 질문에 솔직하게 답하세요

첫 번째 세션은 프롬프팅(prompting)하고 복사하는 것보다 느리게 느껴질 것입니다. 두 번째 세션은 자연스럽게 느껴질 것입니다. 세 번째 세션에 이르면 당신은 예전 방식으로 돌아가고 싶지 않을 것입니다.

소프트웨어 엔지니어, 웹 애플리케이션 구축 경력 4년 이상.

GitHub · LinkedIn