AI-Ready Nx Workspace를 프로덕션 모노레포(monorepo)에 적용하기

우리는 코딩 에이전트에게 작업(/run-task 12.1)을 시작하도록 요청했습니다. 에이전트는 작업 정의를 읽고, 의존성 체인(dependency chain)을 따르다가 다음과 같이 멈췄습니다:

중단(STOP) — 12.1 작업이 차단되었습니다. 이 작업의 게이트(gate)는 아직 실행되지 않은 스파이크(spike)의 라이브 결정 실행(decision-run)과 아직 통과되지 않은 시장 검증(market-validation) 게이트에 의존하고 있습니다. 지금 스키마(schema)를 빌드하는 것은 게이트가 거부할 수도 있는 전제 조건 위에 빌드할 위험이 있습니다.

에이전트는 어떠한 코드도 생성하지 않았습니다. 이러한 거부 반응은 우리가 AI-Ready Nx Workspace로부터 가장 원했던 동작이며, 이 프레임워크가 수행하는 역할의 좋은 예시입니다. 즉, 에이전트가 팀의 주변에서 따로 노는 것이 아니라, 팀이 이미 보유한 아키텍처와 프로세스 내부에서 작동하도록 유지하는 것입니다.

이 포스트에서는 우리가 무엇을 채택했는지, 그리고 그것이 무엇을 변화시켰는지 다룹니다.

문제점

AI-Ready Nx Workspace는 단 하나의 규칙을 중심으로 구축된 템플릿 모노레포(monorepo)입니다:

에이전트는 아키텍처를 소비한다. 아키텍처를 재정의하지 않는다.

이는 코딩 에이전트가 실제 레포지토리(repo)에서 작업할 때 나타나는 세 가지 실패 사례를 해결합니다:

• 설정 파일들이 서로 충돌할 때까지 설정 파일 전반에 걸쳐 아키텍처 결정을 중복해서 내린다.
• 기존에 있는 컨벤션(conventions)을 따르는 대신 새로운 컨벤션을 만들어낸다.
• 문서화되지 않은 품질 게이트(quality gates)를 건너뛴다.

그 구조는 다음과 같습니다: 권한 순서(Authority Order: Nx 프로젝트 그래프, 그 다음 /docs, 그 다음 /.ai, 그 다음 에이전트 전용 파일), 5가지 에이전트 역할, 계층화된 SDLC 파이프라인, ADR(Architecture Decision Records), 그리고 각 도구가 동일한 공유 규칙을 가리키도록 하는 얇은 어댑터 파일(CLAUDE.md, AGENTS.md, .cursor/)로 구성됩니다.

우리는 이를 Nx 모노레포인 StoryCraft에 적용했습니다. StoryCraft는 사용자 스토리를 INVEST 원칙에 따라 점수화하는 요구사항 품질 엔진이며, 호스팅된 MCP 서버, tRPC API, Next.js 앱, 그리고 Supabase 데이터베이스를 포함하고 있습니다.

우리가 채택한 것

재정의하지 말고 소비하라

StoryCraft는 로컬 stdio(packages/mcp) 및 호스팅된 HTTP를 통해 MCP 엔진을 노출합니다. 호스팅된 엔드포인트가 추가되었을 때, tools.ts에 있는 공유 도구 정의(tool definitions)는 수정되지 않은 채로 유지되었습니다. 해당 엔드포인트는 기존의 전송 계층 불가지론적(transport-agnostic) 도구들을 등록하는 어댑터(adapter) 역할을 합니다. 한 ADR(Architecture Decision Record)은 그 경계를 기록했습니다: 만약 호스팅된 전송 계층(hosted transport)이 tools.ts를 수정해야 한다면, 이는 전송 계층이 핸들러(handlers)로 유출(leaking)되고 있음을 의미합니다. 다섯 가지 태스크 웨이브(five-task wave) 동안 해당 파일은 한 번도 변경되지 않았습니다.

계층형 파이프라인 (The tiered pipeline)

태스크는 스토리 포인트(story points)에 따라 분류되며, 실행될 단계(phases)를 결정하는 계층(tier)이 설정됩니다:

최근의 Light 태스크인 호스팅된 엔드포인트를 위한 문서화 및 스모크 프로브(smoke probe) 작업은 네 가지 단계를 모두 실행했습니다: 인간의 확인을 위해 일시 중지하는 태스크 브리프(Task Brief), 게이트(gate) 뒤에서의 구현(nx affected -t lint,test,build를 통과해야 함), 리뷰 단계, 그리고 라이브 서버를 대상으로 프로브를 실행하는 검증 단계입니다. 태스크의 출력 파일은 실행 기록을 남깁니다:

| 지표 (Metric) | 값 (Value) |
| Total phases | 4 |
| Gate failures | 0 |
...

누가 또는 무엇이 실행했는지에 관계없이 모든 태스크는 동일한 기록을 생성합니다.

역할 (Roles)

에이전트는 각 단계마다 서로 다른 역할 파일(role file)을 읽습니다: 브리프를 위한 비즈니스 분석가(Business Analyst), 구축을 위한 구현자(Implementer), diff를 비판하기 위한 리뷰어(Reviewer), 그리고 수락 기준(acceptance criteria)에 따라 검증하기 위해 다시 비즈니스 분석가로 돌아갑니다. 리뷰 지침은 구축 지침과 다르기 때문에, 리뷰 단계는 작성자가 자신의 작업물을 다시 읽는 것보다 더 많은 것을 잡아내는 경향이 있습니다.

작업을 중단시키는 게이트 (Gates that stop work)

위에서 언급한 거부는 이 기둥(pillar)에서 비롯되었습니다. 한 세션에서의 두 가지 예시는 다음과 같습니다:

• Task 12.1이 차단되었습니다. 에이전트는 Depends on (의존) 컬럼을 따라 충족되지 않은 스파이크(spike)와 열려 있는 마켓 게이트(market gate)를 확인했고, 앞으로 나아가 코드를 작성하는 대신 작업을 중단했습니다. 에이전트는 엔지니어링 측면의 필요성과 시장 수요를 별개의 게이트 조건(gate conditions)으로 분리하였으며, 누락된 검증(validation)을 먼저 실행할 것을 제안했습니다.
• Wave D2는 수요에 의해 게이트가 설정되었습니다. 에이전트는 약 20개 항목으로 구성된 전체 계획을 초안으로 작성한 후, 실제 사용 사례를 통해 필요성이 입증될 때까지 '시작하지 않음'으로 표시하였고, 해당 트리거(trigger)를 계획과 함께 기록했습니다.

지속되는 수정 사항 (Corrections that persist)

각 작업 출력에는 '인간의 개입(Human Interventions)' 섹션이 포함됩니다. 이는 인간이 에이전트를 수정한 지점을 나타내며, 다음 작업에서 적용해야 할 교훈으로 작성됩니다. StoryCraft에서 가져온 두 가지 예시는 다음과 같습니다:

• 로드맵(roadmap)에 특정 제3자 제품(third-party product)의 이름이 명시된 경우, 해당 제품을 대상으로 설계하기 전에 여전히 존재하는지 확인하십시오. (제안된 rate-limit 백엔드는 이미 중단된 상태였습니다. 에이전트는 분석 과정에서 이를 식별했습니다.)
• 작업 출력은 .ai/sprints/.../tasks/ 경로에 위치해야 하며, 진행 상황 파일(progress file)은 docs/specs/에 위치해야 합니다. 이들을 같은 위치에 두지 마십시오.

이러한 수정 사항은 리포지토리(repo)에 저장되므로, 동일한 실수가 여러 작업에 걸쳐 반복되지 않습니다.

ADR (Architecture Decision Records)

트레이드오프(trade-offs)가 포함된 결정 사항은 에이전트가 작업하는 동안 읽게 되는 ADR이 됩니다. 호스팅된 엔진의 인증 경계(auth boundary)가 그 예시가 되었습니다. 이후 계정 연결된 웨이브(wave)에서 다른 인증 모델이 필요해지자, 에이전트는 첫 번째 ADR을 수정하는 대신 별도의 ADR을 제안하여 각 ADR이 단일 결정만을 담도록 유지했습니다.

변경된 사항

• 웨이브(wave) 전반에 걸쳐 컨벤션(Conventions)이 일관되게 유지되었습니다: 하나의 어댑터 패턴(adapter pattern), 하나의 커밋 프로세스(commit process), 아티팩트(artifact)당 하나의 위치.

• 에이전트는 검증되지 않은 전제 조건 하에 결과물을 내놓는 대신, 스스로의 작업을 두 번 차단했습니다.

• 각 작업은 동일한 형식으로 브리프(brief), 리뷰(review), 검증(verification), 그리고 메트릭(metrics) 테이블을 남겼습니다.

• 인간의 수정 사항은 일회성 채팅 메시지가 아닌 지속 가능한 규칙이 되었습니다.

• "X가 발생하면 나중에 이것을 빌드하십시오

• /.ai/는 공유 레이어(shared layer)입니다: roles/ (5가지 관점), prompts/ (단계별 가이드), standards/ (코딩, 경계, 보안), workflows/ (티어 정의).

• /docs/에는 ADR(Architecture Decision Records), 아키텍처, 요구사항이 담깁니다.

• 어댑터 파일(CLAUDE.md, AGENTS.md)은 가볍게 유지됩니다. 이 파일들은 규칙을 재진술하는 대신 도구들이 /.ai/를 참조하도록 안내합니다.

• 권한 순서(Authority Order)는 충돌을 해결합니다: Nx 프로젝트 그래프가 문서(docs)보다 우선하며, 문서가 /.ai/보다 우선하고, 에이전트 폴더가 가장 마지막 순위입니다.

• /run-task <id>는 로드맵 행을 읽고, 티어를 분류하며, 의존성을 확인하고, 단계(phases)를 실행합니다. 이때 브리프(brief) 시점과 각 커밋(commit) 전에 인간의 체크포인트를 거칩니다. 에이전트는 커밋 계획을 제안하고, 인간이 커밋을 수행합니다.

도입 비용의 대부분은 이미 내린 결정, 경계, 리뷰 기준, 완료 정의(definition of done)를 에이전트가 반드시 읽어야 하는 곳에 기록하는 데 소요됩니다.

요점 (Takeaway)

우리는 이 프로세스를 통해 보호된 호스팅 MCP 엔진을 출시했으며, 준비되지 않은 두 가지 사항의 출시는 거부했습니다. 가치는 출력량(output volume)에 있지 않았습니다. 에이전트가 기존 아키텍처 내에 머물고, 게이트(gates)에서 멈추며, 우리가 감사(audit)할 수 있는 기록을 남겼다는 점에 있었습니다.

프레임워크: github.com/codeaiforge/ai-ready-nx-workspace