티켓 1장부터 설계를 돌리는 AI 오케스트레이터를 육성한 이야기 ① 사상편: 실패로부터 배우고 설계를 강화해 나가기

Blazor (C#) 기반의 Web 애플리케이션 개발 현장에서 설계 품질을 팀 전체가 일정하게 유지하는 것은 쉽지 않습니다.

"현재 코드 조사 범위가 사람마다 다르다"

"설계서에 써야 할 내용이 생략되어 있어, 잘 아는 사람만이 읽어낼 수 있다"

"코드 조사, 설계서 작성, 티켓 발행, 공수 산정의 각 공정이 단절되어 있다"

이것들은 개발 팀이 직면하기 쉬운 **설계 프로세스의 구조적인 버그 (Structural Bug)**입니다. 경험의 차이에 상관없이 누가 담당하더라도 빠짐없이 양질의 설계를 할 수 있게 하고 싶다——그 동기에서, 저는 터미널에서 동작하는 AI 개발 도구인 "Claude Code"를 베이스로, 티켓 1장으로부터 현황 조사 → 차이점 정리 → 기본 설계 → 상세 설계 → 하위 티켓 발행 → 견적 연계 → 예정 시간 반영까지 일괄적으로 수행하는 AI 오케스트레이터 feature-design-flow를 구축했습니다. 약 3주간의 실전 투입을 거듭하며 키워온 메커니즘입니다.

하지만 처음부터 완성된 형태였던 것은 아닙니다. 현장의 재작업(Rework)이라는 "고통"을 관측할 때마다 품질을 담보하는 게이트(Gate)를 하나씩 추가해 나갔고, 마침내 "스킬 그 자체를 유지보수 대상인 소프트웨어로서 관리하는" 단계에 들어섰습니다. 본 기사는 그 진화의 기록입니다. 그중에서도 흥미로웠던 점은, 수작업으로 설계하던 시절에는 일어나지 않았던 고통이 스킬을 운용하기 시작하면서 새롭게 보이기 시작했다는 것입니다. 예를 들어 "구현 시 확인"이라는 미루기식 표현의 범람이 그러하며, AI에게 설계를 맡김으로써 비로소 현상화되었고, 이를 메커니즘으로 축출하기에 이르렀습니다 (자세한 내용은 섹션 3). 기능 소개라기보다, 설계 프로세스 그 자체를 재설계하고 AI 에이전트(AI Agent)를 육성해 나간 과정으로 읽어주시기 바랍니다. 스킬 정의 (Prompt) 전문과 사용법은 후속편인 실천편에 정리해 두었습니다. 본 기사는 깔끔한 성공담이 아니라, 실패를 메커니즘으로 바꾸어 나간 기록입니다.

1. 설계 프로세스가 안고 있던 "3가지 구조적 버그"

이 메커니즘을 도입하기 전, 우리 팀의 설계 프로세스에는 AI 도입 이전부터 존재하던 3가지 구조적인 문제가 있었습니다.

• 설계의 개인화 (Siloing): 코드 조사 범위, 차이점 추출 방식, 설계서의 목차 구성, 티켓 할당 방식, 공수 산정 방식이 담당자의 머릿속에만 있어, 사람이나 그날의 피로도에 따라 품질이 흔들림.
• 공정의 단절: "코드 조사", "설계서 작성", "티켓 발행", "공수 산정"이 각각 별도의 수작업으로 이루어져, 중간에 전제가 바뀌면 이전 공정으로 돌아가 재작업하는 일이 빈번함.
• 설계서가 작성자의 암묵지 (Tacit Knowledge)에 의존함: 작성자가 도메인에 정통할수록 "이 정도는 안 써도 알겠지"라며 전제를 생략하기 쉬워, 설계서로서 작성해야 할 항목이 누락됨. 도메인을 아는 사람이라면 행간을 읽어 보충할 수 있지만, 처음 접하거나 익숙하지 않은 사람에게는 전제가 생략되어 있어 설계를 재구성할 수 없음.

중요한 점은, 이것들이 AI를 사용하기 이전부터 지속되어 온 프로세스 자체의 문제라는 점입니다. 단순한 "문서 절차서"로 해결하려 하면 현장에서는 형식적으로 흐르기 마련입니다. 그렇기에 절차가 아닌 "Claude Code가 직접 해석하고 실행하는 AI 스킬"로서 프로그래머블(Programmable)하게組み込み(組み込み, 내장), 구조 자체를 교정할 필요가 있었습니다. 또한, 서두에서 언급한 "구현 시 확인"의 범람은 이 세 가지와는 성격이 다르며, 스킬을 운용하면서 비로소 현상화된 고통입니다. 이는 다음 섹션의 시계열 흐름 속에서 다루겠습니다.

2. 모든 것의 출발점: 가슴이 철렁했던 에피소드

이 오케스트레이터의 골격을 결정지은 것은 한 건의 재작업 사례였습니다.

UI만 수정하고 안심하고 있었더니, "보이지 않는 배치"가 동일한 데이터를 쓰고 있었다

어느 금액의 반올림 사양을 개수할 때의 일입니다. "UI의 몇 개 화면을 수정한다"는 방침으로 현황 조사를 마치고, 기본 설계부터 상세 설계, 티켓 발행까지 진행하고 있었습니다.

그런데, 사용자에게 제시하기 전의 타당성 검토 (Validity Review) 단계에서 놓치고 있었던 사실이 드러납니다. UI를 전혀 거치지 않고, 수주 데이터로부터 명세를 일 단위로 자동 생성하는 "백그라운드 배치 처리 (Background Batch Processing)"가 사실은 동일한 테이블에 쓰기 작업을 수행하고 있었던 것입니다. UI 측만 수정해서는 배치 처리를 통해 저장되는 값이 반올림되지 않아 요건을 충족할 수 없었습니다.

다행히 이때는 검토 단계에서 잡아낼 수 있었습니다. 하지만 문제는, 그것이 "검토에서 운 좋게 발견되었다"는 점에 의존하고 있었다는 점입니다. 현황 조사에서는 "UI로부터의 입력"을 확인했으나, UI를 거치지 않는 배치를 처음부터 나열하지 않았던 것입니다.

"확인 (Verification)"과 "발견 (Discovery)"을 분리하기

여기에 이후 설계 사상의 핵심이 있습니다. 인간은 "여기만 보면 충분하겠지"라며 무의식적으로 조사 범위를 좁힙니다. "보겠다고 정한 대상이 예상대로인가"를 확인하는 확인 (Verification) 은 하고 있었지만, "애초에 봐야 할 대상을 누락하지 않았는가"를 찾아내는 발견 (Discovery) 을 하지 못했습니다. 확인은 스코프 내의 기지(Known)만을 처리할 수 있습니다. 존재를 모르는 경로는 확인조차 할 수 없습니다.

리뷰에 의존하는 것은 "최후의 보루"로서는 옳지만, 놓친 클래스의 종류에 따라 재작업(Retake)의 비용이 너무 커질 수 있습니다. 따라서 이러한 종류의 누락은 설계를 작성하기 전의 게이트(Gate) 단계로 앞당겨야 한다——그렇게 생각하여 탄생한 것이, 후술할 "모든 쓰기 경로의 기계적 열거" 게이트입니다. 수정 대상 데이터에 대해 화면, 생성 서비스, 자동 생성 배치, CSV 임포트, API, 일괄 등록과 같은 쓰기의 모든 경로를 grep으로 강제적으로 기계적 열거하게 하고, 각 경로의 현황을 실제 코드로 확인하여 한 줄씩 기록하게 합니다. 범용적인 "확인"이 아니라, 기계적인 "열거"로 수행하는 것이 포인트입니다.

"확인"은 보기로 정한 경로(파란색)의 내용을 검증할 뿐이다. 빨간색 배치처럼 존재를 인지하지 못한 경로는 열거를 통해서야 비로소 시야에 들어온다. 따라서 "발견 = 모든 경로의 기계적 열거"를 설계 전에 배치한다.

이 사건이 우리의 설계 플로우에 품질 게이트를 추가해 나가는 첫 번째 도미노가 되었습니다.

3. 실패에서 배워 키워낸, 6단계의 진화

이 기술은 처음부터 완성된 형태를 설계한 것이 아닙니다. 우선 기본적인 흐름을 만들고, 현장에서 고통을 겪을 때마다 품질 게이트를 하나씩 추가하며, 마지막에는 기술 자체를 유지보수하는——라는 6단계로 성장했습니다. 기사의 뼈대이므로 먼저 전체를 조망하겠습니다.

제1기: 기본적인 일관된(End-to-End) 플로우를 확립하다

가장 먼저 만든 것은 품질 게이트가 없는 "기본 흐름"이었습니다. 기점 티켓의 키를 하나 전달하면, 대화식으로 다음 10단계가 진행됩니다. 각 단계에서 사용자 확인을 거치며, 멋대로 다음으로 진행하지 않는 것이 기본 방침입니다.

기점 티켓 취득·종별 판별— 티켓 종별(신규 기능/수정/버그/리팩터링 등)에 따라 이후의 조사 관점을 전환한다. 자식 티켓의 생성처도 여기서 미리 확인한다.

현황 조사 (코드 + 필요에 따라 DB)— 관련 서비스, 모델, 화면, 정의를 횡단 조사한다.

차이 정리 (4가지 관점)— ①기술적 차이 ②운영 전제·업무적 의도 ③영향 범위 ④판단 방향성,의 4개 축으로 구조화한다.

기본 설계— 템플릿에 따라 작성한다. 변경 내용의 정본은 "변경 사항 목록" 장에 집약하고, 요약이나 각 사양 장은 거기서부터 기계적으로 생성한다.

구현 티켓 분할 제안— 담당 인원, 병행 작업성, PR 사이즈, 테스트 책임, 릴리스 순서를 판단 축으로 하여 2~4개 분할 패턴을 제시한다.

상세 설계 (분할 단위별)— 메서드 시그니처(Method Signature), SQL의 최종 형태, 구 버전 $\rightarrow$ 신 버전 매핑 등, 구현에 그대로 옮길 수 있는 입도(Granularity)까지 구체화한다.

자식 티켓 생성— 설계/구현/리뷰/QA 테스트 티켓을 명명 규칙에 따라 생성한다.

견적 연동 $\rightarrow$ 예정 시간 반영— 견적 기술을 호출하여 결과를 각 티켓의 예정 시간에 반영한다.

입력은 "티켓 1장 + 한마디", 출력은 조사·설계·티켓·견적까지입니다. 도식화하면 이런 일직선 구조입니다.

이 단계에서의 또 다른 중요한 판단은, 판단 규칙이나 템플릿을 기술 본체에 직접 쓰지 않고, 외부 참조 파일로 분리한 것입니다. 차이 정리의 관점, 티켓 분할의 판단 축, 설계서의 장 구성——이것들을 본체에서 분리했습니다. 기술 본체는 "얇은 오케스트레이터(Orchestrator)"로, 지식은 "두꺼운 참조 파일군"으로 만들었습니다. 이 구조가 나중에 품질 게이트를 추가할 때의 개선 용이성을 결정했습니다. 실제로 이후의 각 단계는 이 기본 흐름에 "게이트를 삽입하는" 작업의 연속입니다. 참고로, 여기에 제3기·제4기의 게이트까지 추가한 **완성형의 전체 공정 (10단계)**은 실전편에서 그림으로 정리되어 있습니다. 기본 8단계가 게이트를 거쳐 어떻게 10단계가 되었는지 비교해 보면 진화의 내용을 쉽게 파악할 수 있을 것입니다.

제2기: 페이즈 이월 금지를 추가하다 ── 운영하며 비로소 보인 고통

처음으로 추가한 게이트는, 수작업으로 설계하던 시절에는 일어나지 않았던, 기술을 구동하고 나서야 비로소 현상화된 고통에 대한 대책이었습니다. 어느 날, 기술이 기본 설계를 진행하던 도중, 코드를 몇 분만 보면 확정할 수 있었을 전제——공통 기반의 특정 메서드의 API 시그니처——를 "구현 시 확인"이라고 적고 다음 페이즈로 미루어 버린 것입니다. 미룬 것은 다름 아닌 AI 자신이었습니다.

인간이 설계하던 시절에는 이러한 '확인 가능한 전제'를 무의식적으로 조사한 뒤에 작성하곤 했습니다. 하지만 AI에게 맡기면 확정되지 않은 논점을 태연하게 "구현 시 확인", "상세 설계에서 확정"이라며 미뤄버리고, 설계서에는 미루기 표현이 쌓여갑니다. 이것이 남게 되면 구현자는 설계의 배경을 추적할 수 없게 되고, 설계 판단이 구현 현장으로 새어 나가게 됩니다. 설계서의 신뢰도가 떨어져 다음 유사 프로젝트에서 참고할 수 없게 되는 것입니다.

이러한 고통을 목격하고, 최초의 고통 지점으로서 품질 게이트(Quality Gate)에 "페이즈 이월 금지"를 명문화했습니다. 코드로 파악 가능한 전제(라이브러리 이용 상황, 공통 기반의 API 시그니처, 자동 생성 여부, 기존 리소스 구조 등)는 해당 판단이 필요한 페이즈 내에서 반드시 확인하여 확정하고, 미루기 표현을 본문에 남기지 않습니다. 기본 설계의 완료 조건에 "기본 설계 수준의 확인 사항이 제로(0)일 것"을 설정하고, 미루기 표현의 NG 사례도 참조 파일에 올렸습니다. 이 원칙은 나중에 더욱 정밀해지지만(제6기에서 "미루지 않는다"뿐만 아니라 "너무 앞당기지도 않는다"는 방향으로 경계를 조입니다), 출발점은 바로 이 사건입니다. 기사 제목에 있는 "구현 시 확인"의 추방은 여기서부터 시작되었습니다.

제3기: 스코프 확정 게이트를 추가 (섹션 2의 고통에 대한 대응)

섹션 2에서 언급한 "보이지 않는 배치(Batch)"로 인한 재작업을 계기로, 기본 설계를 쓰기 시작하기 전의 스코프 조기 확정 게이트를 신설했습니다. 이는 소스(Source) 흐름의 "차이 정리"와 "기본 설계" 사이에 끼워 넣은 공정입니다. "대상 화면 / 대상 테이블 / 스코프 외"라는 3가지 리스트를 먼저 굳히고, 그 전 단계로서 모든 쓰기 경로를 기계적으로 열거합니다. 스코프가 굳어지기 전에 본문을 작성하면, 도중에 대상이 증감했을 때 설계 전체를 다시 써야 하는 상황에 처하게 됩니다. 3가지 리스트를 정본(Single Source of Truth)으로 삼아두면, 스코프 변경은 리스트 업데이트 + 영향 범위 장(Chapter)의 부분 수정만으로 끝납니다.

제4기: 6축 설계 타당성 리뷰를 추가

스코프를 확정하더라도 그것만으로는 "전제가 바뀌고 나서야 비로소 나타나는 모순"을 잡아낼 수 없다는 것을 알게 되었습니다. 그래서 기본 설계를 사용자에게 제시하기 전의 게이트로서, 문서의 정합성 체크에 더해 설계의 근본 타당성을 6개 축(6-axis)으로 점검하는 리뷰를 새롭게 포함했습니다 (상세 내용은 섹션 7).

나아가 6개 축 중 가장 비용이 많이 드는 "망라성(Comprehensiveness)", "실현 가능성(Feasibility)"은 제3기의 경로 열거 게이트로 앞당겨(Forwarding) 수행하도록 역할을 배분했습니다. 어떤 지적 사항을 앞에서 해결하고, 어떤 것을 뒤에서 챙길지까지 설계한 것입니다.

제5기: 비대화 대책과 운영 지견의 도입

일관된 흐름(End-to-End)이 정착되는 한편, 생성되는 기본 설계가 너무 망라적이라 부풀어 올라 "결국 어디가 바뀌는지"가 보이지 않게 되었습니다. 이에 따라 **"변경 사항 목록을 정본(SSOT)으로 하는 집필 순서 규칙"**을 도입했습니다 (상세 내용은 섹션 6).

동시에, 장시간 세션에서 AI의 출력이 불안정해지는 현상에 대한 대처로서 "큰 본문을 동반하는 기표(Ticket) 생성은 1턴에 1건씩"과 같은 운영 규칙을 명문화했습니다 (상세 내용은 섹션 4). 고통은 설계의 질뿐만 아니라, AI 에이전트의 동작 안정성에서도 온다는 깨달음입니다.

제6기: "기능 추가"에서 "유지보수"로 — 스킬 자체의 리팩터링 (Refactoring)

지금까지의 진화는 모두 "게이트를 추가한다 = 기능 추가"였습니다. 덧붙이기를 거듭한 결과, 프롬프트 기술이 패치워크(Patchwork)처럼 변하며 구조적으로 복잡해졌고, "출력이 흔들리거나 누락이 발생하는" 전조가 보이기 시작했습니다. 프롬프트도 코드와 마찬가지로, 덧붙이기에 따른 부채를 방치하면 AI는 미아가 됩니다. 그래서 방향을 바꾸어

• 페이즈 경계의 정밀화: 「이월 금지」를 철저히 지키려다 보니, 기본 설계(Basic Design)에 상세 설계(Detailed Design) 수준의 코드 표현이 새어 나오고 있었습니다. 사전 확인의 중요성은 유지하되, 행 번호·인수명·로컬 변수명과 같은 구현 특유의 사항은 기본 설계에 쓰지 않도록 경계를 다시 설정했습니다. 페이즈 이월 금지를 「미루지 않는」 방향뿐만 아니라 「너무 앞당기지 않는」 방향으로도 조였습니다.
• 스코프 외 성과물의 취급 명확화: 기능 점수(Function Point) 값 등 본 스킬의 범위 외 항목은 빈 칸으로 유지하고 별도 페이즈에서 채우도록 완료 조건에 명시했습니다. 「해당 값의 정본(Source of Truth)이 어느 페이즈에 있는가」를 모호하게 만들지 않습니다.
• 구조의 공통화: 여러 단계에서 재사용하는 리뷰 관점표를 본체에서 참조 파일로 외부에 분리하여, 이중 유지보수를 한 곳으로 집약했습니다.
• DB 영향 판단의 필수화: 네트워크나 로컬 DB 환경이 없다는 이유로 영향 조사가 뒤로 밀리지 않도록, 「환경이 없더라도 스키마 문서(Schema Document) 참조를 통해 DB에 대한 영향 유무를 판단하는 것까지는 필수」라고 명시하여 변명의 여지를 없앴습니다.
• 스텝 번호 정리: 누락된 번호나 계층의 불일치를 재정렬하여 참조 실수를 방지했습니다.

제6기의 핵심은, 스킬을 「움직이는 문서」가 아니라 「유지보수 대상인 소프트웨어」로서 지속적으로 관리해 나가는 단계에 진입했다는 점입니다.

4. Claude Code의 제약과 마주하기: 컨텍스트 비대화와 출력 길이

게이트를 추가할수록 설계의 정밀도는 높아졌지만, 실전 투입을 거듭하면서 AI 에이전트 특유의 두 가지 기술적 제약에 부딪혔습니다. 바로 컨텍스트(Context)의 비대화와 1회 응답당 출력 길이입니다. 장시간 세션에서는 내부의 도구 실행 JSON이 파싱 실패(malformed)를 일으키거나, 직전에 합의한 스코프를 잊어버리고 미아가 되곤 합니다. 이는 정신론이 아니라, **데이터 유량 제어 (아키텍처 설계)**를 통해 해결하고 있습니다.

① 컨텍스트 비대화에 대한 대처

• 티켓의 GET/UPDATE를 반복하지 않기: Backlog의 취득·갱신 API는 호출할 때마다 필드 전체를 주고받으며, 티켓 1개당 수백 KB를 소비합니다. 불필요한 GET을 최소화하고, 갱신은 필요한 차분(Delta)에만 집중합니다.
• Write한 파일의 즉시 다시 읽기 금지: 작성 직후의 설계서를 스스로 다시 읽으면, 출력 결과가 컨텍스트 내에서 이중 계상되어 토큰을 압박합니다. 이를 명시적으로 금지했습니다.
• 무거운 조사를 서브 에이전트(Sub-agent)로 격리: 광범위한 Grep·DB 조사·PR diff 취득은 메인 컨텍스트를 심하게 오염시키므로, 독립된 서브 에이전트로 격리하고 메인은 「결론의 요약만 받는」 구조로 만듭니다.

② 1회 응답당 출력 길이 (malformed JSON)에 대한 대처

입력 컨텍스트에 여유가 있더라도, 한 턴(Turn)에 대량의 사고와 거대한 도구 호출(수천 자의 티켓 작성 등)을 동시에 수행하면 JSON 출력이 도중에 끊겨 파싱 에러가 발생합니다. 이는 비대화와는 별개의 제약입니다.

• 대형 티켓 작성은 1턴에 1건씩 순차 실행: 여러 티켓을 1회 응답으로 병렬 작성하게 하지 않고, 설명(Description)이 큰 경우에는 1건씩 순차적으로 작성합니다.
• 채팅에 전문 재게시 금지: 생성물의 전문을 화면에 에코(Echo)하지 않고, 「요점 + 링크」로 나타냅니다.

직접 해보며 느낀 점은, LLM의 불안정성은 「똑똑하게 쓰면 고쳐지는」 종류의 것만은 아니라는 사실이었습니다. 무엇이·얼마나 컨텍스트로 흘러 들어오고, 1회 응답에서 몇 바이트를 뱉어내는지와 같은 데이터 유량을 물리적으로 깎아내는 것만으로도 상당히 안정되었습니다. 미미해 보이지만, 제 경우에는 이 방법이 가장 효과적이었을지도 모릅니다.

5. DB 변경 분리 원칙: 배포·운영까지 내다본 분할

티켓 분할을 AI에게 맡길 때, 「작업량이 균등하도록 나눠줘」라고만 해서는 실무에 견딜 수 있는 티켓이 나오지 않습니다. 특히 공을 들인 부분은, DB 변경(마스터 데이터·스키마 변경)을 독립된 구현 티켓으로 분리하는 원칙입니다.

코드 수정과 DB 마이그레이션(Migration)을 한 티켓에 섞으면, 배포 중에 구 버전 코드와 신 버전 코드가 동시에 가동되는 순간에 적용 타이밍을 제어할 수 없게 되어, 구 버전 코드가 신 버전 스키마를 읽고 크래시(Crash)가 발생하는 원인이 됩니다. 롤백(Rollback) 시에도 데이터의 롤백 전략까지 덩달아 복잡해집니다. 이 지식을 외부 레퍼런스에 「3분할 표준 패턴」으로 정의했습니다.

분할 단위	주요 작업	운용상의 이점
1. DB 마이그레이션 (DB Migration)	추가 SQL (선 적용) + 삭제 SQL (보관 후 추후 적용)	SQL 단독으로 리뷰할 수 있으며, 구 버전 코드가 동작 중일 때도 안전한 「데이터 잔치 → 사후 삭제」 전략을 취할 수 있음
2. 모델·UI 계층	상수, enum, 리소스 문자열, 화면 항목 추가	「그릇」을 먼저 만들어 PR(Pull Request) 크기를 작게 유지하고 (500행의 벽), 병행 작업성을 높임
3. 로직 개수 (Logic Modification)	비즈니스 로직, 화면 서비스, 단위 테스트 (Unit Test)	그릇이 갖춰진 상태에서 메인 로직과 테스트에 집중할 수 있음

여기서 효과를 본 것은, AI에게 분할을 맡길 때의 판단 기준을 「작업량을 균등하게」가 아니라 「리뷰하기 쉬운 단위인가」, 「단독으로 롤백(Rollback)할 수 있는가」, 「적용 타이밍을 나눌 수 있는가」로 전달한 것이었습니다. 릴리스 시에 곤란해지는 점을 설계 상류 단계인 티켓 분할 단계에서 미리 잘라두니, 제 후속 공정이 상당히 편해졌습니다.

6. AI의 모순과 비대화를 억제하는 「정본(SSOT)」 문서 설계

AI에게 설계서를 쓰게 하면, 장(Chapter)을 넘나들며 내용이 모순되거나 어긋납니다. 망라성(Comprehensiveness)을 너무 의식하게 만들면 문서는 무한히 부풀어 오릅니다. 이를 기본 설계 템플릿과 집필 순서 규칙을 결합하여 억제했습니다.

핵심은 『변경 사항 목록』 장을 유일한 정본(Single Source of Truth, SSOT)으로 만드는 것입니다.

• 먼저 변경 사항 목록을 확정한다: 레이어별 표(현상 ⇄ 신규 사양)를 먼저 완성한다. enum 명칭, 마스터의 Value, 파일 경로 등의 구체적인 값은 모두 이 장에만 기술하여 일원화한다.
• 요약을 기계적으로 작성한다: 확정된 정본으로부터 서두의 변경점 요약을 한 줄씩 기계적으로 생성한다.
• 사양 장은 요약에 그친다: 기능 요구사항, 처리 사양, 화면 사양 장에는 구체적인 값을 쓰지 않고, 동작이나 방침의 요약에 머물게 한다. 중복될 것 같은 부분은 「구체적인 내용은 변경 사항 목록을 참조」라고 쓰게 하여, 이중 기술을 철저히 금지한다.

정보를 3계층으로 나눈 것입니다. 정본(변경 사항 목록) / 개요(요약) / 요약(각 사양 장). 동일한 구체적 값을 두 번 쓰지 않는 규칙이 비대화와 「변경점이 묻히는」 문제를 동시에 해결합니다. 이와 함께 기본 설계(파일 단위로 무엇을·왜)와 상세 설계(구현의 구체값 = 시그니처(Signature), SQL 최종 형태, 전체 매핑)의 경계를 명문화하여 이중 기술을 없앴습니다.

이 순서로 쓰게 한 이후부터, 장을 넘나드는 모순과 문서의 팽창이 상당히 줄어들었습니다. 영리한 프롬프트로 모순을 억제하려 하기보다, 정본을 하나 정하고 나머지는 거기서 기계적으로 파생시키도록 정보의 배치 방식을 바꾸는 것이 더 효과적이었다는 것이 제 실감입니다. 설계서뿐만 아니라, AI에게 긴 문장을 쓰게 할 때는 비슷한 일이 일어나지 않을까 생각합니다.

7. 「문서가 정돈되어 있음」 그 너머를 보다: 6축 설계 타당성 리뷰

제시 전의 리뷰는 2단계입니다. 하나는 문서 정합성 리뷰로 「제대로 작성되었는가」를 보고, 다른 하나는 설계 타당성 리뷰로 「설계가 타당한가」를 봅니다. 후자를 체계화하기 위해 6가지 축을 세웠습니다. 요구사항 충족·추적성(Traceability) / 망라성(Comprehensiveness) / 정합성(Consistency) / 실현 가능성(Feasibility) / 영향 및 가역성(Reversibility) / 검증 가능성(Verifiability)의 6가지입니다.

이 6축은 즉흥적으로 만든 것이 아닙니다. 그중 5개 축은 요구공학의 국제 표준인 ISO/IEC/IEEE 29148의 품질 특성(correct / complete / consistent / feasible / verifiable)에 대응하며, 「영향 및 가역성」만이 설계 리뷰 고유의 보강(유지보수성·변경 용이성을 다루는 ISO/IEC 25010에 가까운 내용)입니다. 기존 표준을 토대로 함으로써, 리뷰 관점에 「왜 그 축인가」라는 근거를 부여했습니다.

리뷰는 고정된 체크리스트를 가지지 않습니다. 각 안건에 대해 서브 에이전트(Sub-agent)가 안건 고유의 리스크를 동적으로 생성합니다. 고정 리스트는 유지보수 비용이 들고, 안건별로 날카로운 지적을 내기 어렵기 때문입니다. 서브 에이전트에게는 사전 문맥을 전달하지 않고, 설계서와 실제 코드만을 보여주며 비판적으로 검증하게 하여, 추측으로 「문제 없음」이라고 판단하지 않게 합니다.

리뷰 관점을 제 즉흥적인 생각으로 나열하는 대신, 이미 존재하는 표준을 골격으로 삼음으로써 「왜 이 관점인가」를 스스로도 설명할 수 있게 된 점이 도움이 되었습니다. 또한, 체크리스트를 고정하여 계속 유지보수하기보다, 관점만 고정하고 구체적인 내용은 그때마다 생성하게 하는 것이 안건별 날카로움과 수고의 절감을 동시에 달성할 수 있었던 것 같습니다. 이 부분은 안건에 따라 다르므로 항상 잘 된다고까지는 말할 수 없지만 말입니다.

8. 기술의 생태계: 단일 기능을 묶는 핵심 오케스트레이터

지금까지 feature-design-flow를 단일 스킬로서 설명해 왔지만, 실제로는 단독으로 완결되지 않습니다. 설계부터 품질 보증(QA), 그리고 학습까지 순환시키는 **스킬 군의 중심(Orchestrator, 오케스트레이터)**으로 위치시키고 있습니다. 설계 판단은 이 스킬이 담당하고, 그 전후에 있는 전문 공정은 각각 별도의 단일 기능 스킬에 위임하는 구성입니다.

• 요구사항 리뷰 계열 (사전 단계): 설계에 들어가기 전, 요구사항이 테스트 설계까지 진행할 수 있는 품질인지 GO / 조건부 GO / NO GO로 판정합니다. 핵심 스킬을 기동하기 전의 문지기 역할을 합니다.
• 견적 계열: 표준 견적과 기존 구현의 '유용률(Reuse rate)'을 평가하는 견적의 두 종류를 가집니다. 핵심 스킬은 미루기 표현(先送り表現)이 생기지 않도록 고정 설정(요구사항 텍스트 작성·상세 설계·리뷰·버퍼·테스트 정의)을 매번 갖추어 이 견적 스킬을 호출합니다.
• QA 계열: 테스트 계획 작성 → 테스트 케이스 작성 → 테스트 케이스 리뷰의 3단계로 이루어집니다. 여기가 포인트인데, 핵심 스킬은 QA 티켓의 '틀'만 만들고, 테스트 계획서의 본체는 만들지 않습니다. 정보가 부족한 상태에서 포괄성(Comprehensiveness)이 담보되지 않은 테스트 계획을 양산하지 않기 위한 의도적인 책임 분리입니다. 테스트 본체는 QA 공정에서 QA 전용 스킬이 별도의 타이밍에 작성합니다.
• 학습 계열: 리뷰나 회고를 통해 얻은 재발 방지 관점을 '관점 데이터베이스'에 축적하여 다음 설계·리뷰로 환류(Feedback)시킵니다. 고통 속에서 태어난 게이트를 개인의 기억이 아닌 시스템으로 쌓아가는 회로입니다.

이 구성의 사상은 명쾌합니다. 바로 '거대한 만능 스킬'을 만들지 않는 것입니다. 하나의 프롬프트(Prompt)에 모든 것을 집어넣으면 개선할 때마다 거대한 본체를 건드려야 하므로 부작용을 예측할 수 없게 됩니다. 대신 책임이 명확한 단일 기능 스페셜리스트를 준비하고, 핵심 오케스트레이터가 이를 묶습니다. 설계를 바꾸고 싶을 때는 설계 스킬을, 견적 로직을 바꾸고 싶을 때는 견적 스킬을 건드리는 식으로 개선이 국소화될 수 있습니다.

이 구성으로 진행하면서, 하나의 덩어리로 된 만능 에이전트(Agent)를 만들지 않은 것이 정답이었다고 생각합니다. 책임을 나누어 두면 각 스킬을 별도로 수정할 수 있고, 어디를 건드리면 무엇이 변하는지를 스스로 추적할 수 있습니다. 핵심 스킬이 '스스로 할 일'과 '다른 스킬에 위임할 일(틀만 만들기)'의 경계선을 가지고 있는 것이, 시스템이 파탄 나지 않고 유지될 수 있는 이유라고 느낍니다.

9. 되돌아보며, 특히 효과적이었다고 생각하는 점

지금까지 여러 가지를 썼지만, 직접 해보며 스스로 효과를 느꼈던 점은 주로 세 가지입니다.

첫 번째는, 확인이 아니라 '발견'을 설계 앞에 두었다는 것입니다. "여기만 보면 충분하겠지"라는 선입견은 제 의지만으로는 지울 수 없었습니다. 대상 데이터로 가는 모든 경로를 기계적으로 열거한다는 절차로 정립하고 나서야, 보이지 않았던 배치(Batch)가 시야에 들어왔습니다. 똑똑하게 하려고 노력하기보다, 기계적으로 수행하는 공정을 하나 끼워 넣는 것이 저의 간과를 막는 데 효과적이었습니다.

두 번째는

파일 구성 지도 (어떤 파일이 무엇을 하고 있는지) /

SKILL.md

전문 / references/

각 파일 전문 / 자신의 팀에 맞춰 커스터마이징할 때의 핵심 포인트(勘所)를 기재하고 있습니다.

11. 마치며: "입력은 얇게, 출력은 두껍게"

이 아키텍처 (Architecture)를 통해, 개발자는 터미널에서 시작 티켓을 한마디 전달하는 것만으로, 배후에서 현상 조사, 코드 확인, 규격을 토대로 한 리뷰 게이트 (Review Gate)가 차례로 실행되어, 최종적으로 Backlog에 구조화된 티켓군과 예상 시간이 반영되게 되었습니다. 입력은 티켓 1장 + 한마디, 출력은 조사·설계·티켓·예상 시간까지. 입력은 얇게, 출력은 두껍게 —— 이것이 목표로 한 형태입니다.

AI에게 설계를 통째로 맡겼다가 환각 (Hallucination) 현상 때문에 고생한 적도 있었고, 수작업 그대로였다면 계속해서 업무의 개인화 (属人化) 문제로 고민했을 것입니다. 지금의 형태는 그 사이 어딘가에 안착했다는 느낌입니다. 인간의 선입견으로 놓치는 부분은 기계적인 열거로 미리 방지하고, LLM이 불안정해지는 부분은 데이터 주입 방식으로 억제하며, 스킬 (Skill) 자체는 방치하지 않고 계속해서 관리해 나간다 —— 하고 있는 일은 이것뿐이며, 특별한 것은 하지 않았습니다.

그리고 무엇보다, 이러한 품질 게이트 (Quality Gate)들은 처음부터 설계되어 있었던 것이 아닙니다. 먼저 현장에서 뼈아픈 경험을 하고, 그것을 반복하지 않기 위해 나중에 하나씩 추가해 나갔을 뿐입니다. 만약 설계 리뷰를 감각에 의존해 수행하고 계신 분이 있다면, 그중 몇 가지는 시스템으로 대체할 수 있을지도 모릅니다. 제 경우에는 그랬다는 이야기로 받아들여 주시면 좋겠습니다.

Discussion