프런트엔드 AX 설계기 0편 — 레거시 3개와 차세대 FE를 위한 워크플로우 설계기

1. 도입부 (Why This Matters)

React 15에 묶인 레거시 프로젝트 3개와, Next.js 기반 차세대 프로젝트들을 한 사람이 동시에 굴리는 상황을 떠올려 보자. 프로젝트마다 컨벤션이 다르고, 빌드 함정이 다르고, "여기서는 이렇게 하면 안 된다"는 암묵지가 다르다. 컨텍스트 스위칭 비용만으로도 하루가 샌다.

여기에 AI를 얹으면 처음엔 빨라진 것 같다. 그런데 곧 다른 종류의 비용이 보인다. 채팅창에 그때그때 프롬프트를 복붙 하니 결과가 매번 다르고, AI가 건드리면 안 되는 곳을 건드려도 막을 경계가 없고, 잘 된 흐름을 재현할 수도 팀에 넘길 수도 없다. 산발적 사용의 한계는 속도가 아니라 운영 가능성에서 드러난다.

이 글은 그 한계를 마주한 FE 한 명이 4개월에 걸쳐 AI 워크플로를 "설계"로 끌어올린 기록의 입구다. 이 글을 읽고 나면 (1) 왜 팁 모음이 아니라 설계가 필요한지, (2) 그 설계가 어떤 4개의 축으로 묶이는지, (3) 11편 중 어디부터 읽으면 되는지를 얻는다. 예상 소요: 약 8분.

2. 핵심 개념 (What & Why)

먼저 신생 용어 두 개를 한 줄로 정의하고 넘어가자. 둘 다 아직 자리 잡는 중인 말이라 용어 자체에 무게를 싣지는 않는다.

• 바이브 코딩(vibe coding): AI 에이전트와 함께 코드를 만드는 개발 방식. 즉 개발 과정에 AI가 들어온 것.
• AX(Agent Experience): 에이전트를 위해, 에이전트와 함께 쓰도록 인터페이스를 설계하는 일. 즉 제품 표면에 AI가 들어온 것.

비유하자면 AI에게 일을 맡기는 것은 유능하지만 처음 온 신입에게 일을 맡기는 것과 같다. 신입에게 우리는 무엇을 하는가? 건드려도 되는 것과 안 되는 것을 정하고(권한), 결과를 검수하고(게이트), 신뢰가 쌓이면 재량을 늘리고(자율성), 온보딩 문서를 정비한다(운영). AI도 정확히 같은 네 가지가 필요하다. 산발적 프롬프트에는 이 넷이 전부 빠져 있다.

여기서 중요한 연결고리 하나. 이건 FE의 본업에서 벗어난 일이 아니다. FE의 본질은 "사람과 시스템 사이의 인터페이스를 설계·구현하는 craft"다. 그 인터페이스의 양 끝에 이제 사람만이 아니라 AI가 들어온다 — 우리가 AI와 함께 만들고(바이브 코딩), AI를 위해 만들기(AX) 때문이다. AI 워크플로를 설계한다는 것은 개발자와 에이전트 사이의 인터페이스를 설계한다는 뜻이고, 그건 영역이 넓어진 FE의 일이다. 표면이 사람이든 에이전트든, 인터페이스를 잘 만드는 craft는 하나다.

그래서 이 시리즈는 "Claude Code 팁 모음"이 아니다. 팁은 개별 기교지만, 여기서 다루는 건 팀 단위 운영을 전제로 한 권한·검증·자율성·운영의 설계다.

3. 동작 원리 (How It Works)

설계는 크게 4-layer 책임 분리라는 뼈대 위에서, 4개의 축으로 펼쳐진다.

프론트엔드 AX 설계기 — 시리즈 지도

 

뼈대: 4-layer 책임 분리

산발적 사용이 위험한 핵심 이유는 "권한"과 "재사용"과 "실행"이 한 덩어리로 뭉쳐 있다는 데 있다. 이걸 네 겹으로 가른다.

1. Public command — 사람이 부르는 진입점. 이름·인자·게이트만 책임진다. 권한 게이트가 여기 있다.
2. Internal skill — 여러 커맨드가 공유하는 재사용 계약. 단, skill 자체는 권한 경계가 아니다. (이 명제가 1편의 주제다.)
3. Shared docs — 권한 경계 매트릭스 같은 공유 가이드. 결정의 근거를 한 곳에 모은다.
4. Agent — 권한 분리 실행. tool scope로 "이 작업은 읽기 전용 도구만" 같은 식으로 권한을 분배한다.

권한은 skill에 숨기는 게 아니라 public command의 게이트 · 명시적 사용자 확인 · agent의 tool scope 세 곳으로 분배된다. 이 원칙 하나가 나머지 설계 전체의 토대다.

4개의 축

• 권한 경계 — AI가 무엇을 건드릴 수 있나. (1편 skill≠경계, 2편 agent 기본 OFF, 8편 자율 모드 경계, 9편 외부 도구(MCP) 경계)
• 검증 게이트 — 결과를 어떻게 믿나. (4편 Claude 분석·Codex 비평의 교차 검증, 5편 writer/evaluator 분리, 6편 게이트 보정·철회·earn-back, 7편 AI 변조·CI-gaming 탐지)
• 라이프사이클 — 계획과 구현을 어떻게 잇나. (3편 양방향 spec lifecycle)
• 운영 결정 — 무엇을 계속 유지·폐기하나. (10편 모델 선택 운영, 11편 운영 루프 회고)

각 편은 독립된 "결정 + 측정" 아크라서, 어느 편부터 읽어도 성립한다. 0편(이 글)은 그 전체 지도와 "왜 설계가 필요했나"를 담는 입구다.

4. 실무 적용 (Practical Examples)

축적된 규모를 먼저 정직하게 밝히면, 약 4개월간 200+ 커밋, 공개 커맨드 13개·내부 skill family 10개·에이전트 6개로 수렴했고, 정식 릴리스 흐름(CHANGELOG·semver·릴리스 노트·공지)으로 v0.1.0부터 v0.6.1까지 운영했다. 이 숫자는 생산성 배수가 아니라 들인 노력과 범위를 가리킨다. "AI로 N배 빨라졌다" 류 주장은 측정 조건 없이는 하지 않는다.

✅ 권장 패턴 (Good Practice)

책임을 4-layer로 가르고, 진입점은 게이트를 명시한다.

<!-- commands/ship.md — public command: 이름·인자·게이트만 책임진다 -->
---
description: 변경분을 검증하고 릴리스한다
argument-hint: [patch|minor|major]
---
1. 검증 게이트: 테스트·린트·타입체크 통과 확인 (실패 시 즉시 중단)
2. 사용자 확인: 버전 범프 내용을 명시하고 명시적 승인을 대기
3. 실행: 승인 시에만 release 에이전트에 위임 (해당 agent는 제한된 tool scope)

# 디렉터리도 책임별로 갈라 둔다
commands/   # public  : 사람이 부르는 진입점 + 게이트
skills/     # internal: 재사용 계약 (권한 경계 아님)
agents/     # 실행    : tool scope로 권한 분리
docs/guides/# shared  : 권한 경계 매트릭스 등 결정의 근거

핵심은 세 가지다. 게이트가 진입점에 보이게 있고(2단계 전 1단계가 막는다), 위험한 실행은 명시적 승인 뒤로 미루며, 실행 권한은 agent의 tool scope로 좁힌다.

❌ 안티패턴 (Anti-Pattern)

# 모든 규칙·권한·예외가 한 파일에 뒤섞임
~/.claude/CLAUDE.md   # 수천 줄, 무엇이 무엇을 막는지 추적 불가
# 실행: 매번 채팅창에 긴 프롬프트를 복붙, 사람마다 표현이 다름

무엇이 문제인가? 권한 경계가 어디에도 명시되지 않아 AI가 무엇이든 건드릴 수 있고, 같은 작업도 사람·시점마다 결과가 달라 재현이 안 되며, 잘 된 흐름을 팀에 넘기거나 회귀를 추적할 수 없다. 빨라 보이지만 운영이 불가능하다.

🔍 실행 결과

권장 패턴에서 /ship minor를 부르면, 테스트가 깨진 순간 1단계에서 멈춘다. 통과하면 "minor 범프: 0.6.1 → 0.7.0" 같은 내용을 보여주고 사람의 승인을 기다린다. 승인 후에야 tool scope가 제한된 에이전트가 릴리스를 수행한다. 같은 명령은 누가 부르든 같은 게이트를 통과하므로 재현 가능하고, 그대로 팀에 공유된다.

5. 장단점 및 고려사항

장점	단점
✓ 권한 사고를 게이트·승인·scope로 구조적으로 차단	✗ 초기 설계·정비 비용이 든다 (산발적 사용보다 느린 출발)
✓ 재현 가능 — 같은 명령은 같은 결과 게이트를 통과	✗ 도구 스펙 변화에 맞춰 지속 유지보수 필요
✓ 팀 공유·온보딩이 명령 한 줄로 가능	✗ 과설계 위험 — 1인·소규모엔 무거울 수 있음
✓ 회귀·변조를 검증 게이트로 조기 포착	✗ 측정 없이 "효과"를 주장하면 hype가 된다

도입 체크리스트(작게 시작):

1. 가장 위험한 작업 하나(예: 릴리스·마이그레이션)부터 게이트 + 명시 승인으로 감싼다.
2. 권한이 "어디서" 분배되는지 한 장의 표(권한 경계 매트릭스)로 적는다.
3. 자주 쓰는 흐름 1~2개만 public command로 고정해 재현성을 확보한다.
4. 효과는 측정 조건과 함께만 기록한다(예: "이 코퍼스 기준 토큰 N% 절감(추정)").

흔한 함정: skill에 권한을 숨겨두고 "경계를 세웠다"라고 착각하는 것. skill은 재사용 계약일뿐 권한 경계가 아니다(→ 1편).

6. 결론 및 다음 단계

핵심 3줄 요약:

• 산발적 AI 사용의 한계는 속도가 아니라 운영 가능성(권한·재현·공유)에서 드러난다.
• 해법은 팁이 아니라 설계 — 4-layer 책임 분리 위에 권한·검증·라이프사이클·운영 4개 축을 얹는다.
• 이건 곁다리가 아니라 개발자와 에이전트 사이 인터페이스를 만드는, 넓어진 FE의 본업이다.