본 기사의 위치— 본 기사는 awslabs/aidlc-workflows 리포지토리의 규약 규칙 및 이용 가이드를 소재로, 필자가 AI를 활용하여 읽어내고 정리한 해석입니다. AWS가 공식적으로 발표한 방법론도 아니며, 1차 자료의 번역이나 요약도 아닙니다.

시리즈— 본 기사는 AI로 풀어보는 AI-DLC v2 시리즈의 일부입니다.

참조 버전— Claude Code 구현을 대상으로, 2026년 6월 시점의 v2.1.3(커밋 c95070e, core/)를 참조하고 있습니다. Kiro・Codex 구현은 대상이 아니며, 기술서가 다를 수 있습니다. OSS 구현은 업데이트가 지속되고 있으므로, 최신 상태는 공식 리포지토리를 확인해 주십시오.

AI-DLC v2의 각 메커니즘은 문서나 개념도 상에서는 정연하게 작동합니다. 하지만 구현(core/)에 들어가면, '조언에 그치고 멈추지 않는 검증', '타입은 있지만 아직 발행되지 않은 지시', '주석이 실체에 미치지 못하는 곳'과 같은 단차가 보입니다. 이것들은 결함의 고발이 아니라, 빠르게 움직이는 구현에 주석・타입・문서가 따라잡는 과정 중인 현재의 한계점입니다.

본 기사는 도입을 검토하는 입장을 대상으로, 각 메커니즘의 작동 원리 자체는 개별 기사에 맡기고, 그 '한계점 및 주의사항' 측면만을 출처와 함께 일목요연하게 보여줍니다. 어디까지를 사양으로 신뢰할 수 있고, 어디부터가 미래인지 말하지 않고 과장하지 않으며, 소스에 근거하여 읽어냅니다.

'검증 게이트가 자동으로 차단한다'는 이해는 구현상 성립되지 않습니다. 워크플로우를 멈추게 하는 유일한 메커니즘은 사람의 승인 게이트이며, 그 외의 '검증'은 모두 조언(advisory)입니다.

센서 4개 모두 default_severity: advisory 입니다. 발화 후크는 항상 exit 0을 반환하는 계약(aidlc-sensor-fire.ts,

뿐입니다(aidlc-state.ts).

합격/불합격을 결정하지 않는 감사 마커(audit marker)이며, "이 페이즈는 검증을 통과했다"라는 판정이 아닙니다. 이름에서 "검증 게이트(verification gate)"를 연상하면 오독하게 됩니다. 자세한 내용은 별도 기사 「페이즈 경계 검증」, 「상태와 감사」에서 다룹니다.

CI나 파이프라인에 "자동으로 중단되는 문"을 기대하며 이 메커니즘을 배치하면 기대와는 다를 것입니다. 조언에 그치는 검증은 통지와 감사 기록을 남길 뿐, 중단할 권한은 없습니다. 품질을 강제하고 싶다면, 중단하는 역할은 사람의 승인 게이트(approval gate) 측에 설계한다는 전제가 필요합니다.

메커니즘에 따라 타입(type)으로는 정의되어 있어도, 아직 실제로는 발행되지 않는 것들이 있습니다. "존재하는 것"과 "동작하는 것"은 별개입니다.

진행 엔진(progression engine)이 다음 단계로 반환하는 지시(directive)는 판별 공용체(discriminated union, 태그로 종류를 구분하는 타입)로서 9종이 정의되어 있습니다. 이 중 엔진이 실제로 발행하는 것은 7종으로, run-stage, invoke-swarm, ask, print, error, done에 parked(장기 워크플로우를 스테이지 경계에서 일시 정지하는 종단 지시)가 포함됩니다. 남은 dispatch-subagent와 present-gate 2종은 타입으로는 존재하지만 발행되지 않습니다. 주석 자체에 "present-gate and dispatch-subagent — arrive in later waves; this handler … cleanly omits those two"라고 적혀 있습니다(aidlc-orchestrate.ts).

설계상의 "예약"과 미구현은 별개의 문제입니다. 이 2종은 향후의 파도(later waves)를 위한 예약 슬롯이며, 타입에 틀을 확보해 두면 나중에 발행을 추가할 때 스키마를 확장하지 않아도 됩니다. 읽는 입장에서는 타입에 있다고 해서 "사용 가능하다"라고 전제하지 않는 것이 안전합니다. 지시의 전체 모습은 별도 기사 「진행의 핵심」에서 다룹니다.

소스의 주석이나 산문이 동일한 core/ 내의 실체와 어긋나 있는 부분이 있습니다. 여기서는 공식 docs를 한쪽으로 사용하지 않고, core/ 내에서 완결되는 불일치(코드 대 코드, 산문 대 집계)만을 모았습니다.

드리프트 (Drift)	주석/산문의 주장	실체 (v2.1.3)	출처
스테이지 수	docstring이 일관되게 "31 stage files"라고 기술	스테이지 정의는 32개	aidlc-graph.ts:8,1207,1263 대 stages/** 실제 개수
전체 스테이지 실행 스코프	enterprise가 "전체 32개를 실행하는 유일한 스코프"라고 기술	feature도 전체 32개를 실행. 산문끼리 모순	scopes/aidlc-enterprise.md 대 aidlc-feature.md 대 프론트매터(frontmatter) 집계
스코프별 스테이지 수 (§8 표)	mvp 약 25, bugfix 약 8, refactor 약 9, security-patch 약 10, workshop은 표에 없음	실제 집계는 mvp 22, bugfix 7, refactor 8, security-patch 9, workshop은 25로 표에서 누락	stage-protocol.md §8 대 scopes: 집계
규칙 해결 체인 (Rule resolution chain)	core 내의 이용 가이드가 {{HARNESS_DIR}}/rules/와 "5층 (…→stage)"을 기술	코드는 core/memory/ 하위에서 org→team→project→phase의 4층이며, stage 층은 없음	rules-reading.md 대 aidlc-graph.ts (SCOPE_PRIORITY)

scopes: 프론트매터를 전체 32개로 집계한 실제 수치는 다음과 같습니다 (참고).

scope	실행하는 스테이지 수
enterprise	32 / 32
...

이것들은 "버그"가 아니라, 빠르게 동작하는 구현에 주석이나 개략적인 산문이 어긋나 있는 전형적인 사례입니다. 읽는 입장에서는 core/의 주석이나 개략적인 표를 확정된 값으로 맹신하지 말고, 필요하다면 실체(파일 수, 프론트매터)를 세어서 확인하는 것이 안전합니다. 스코프의 내역은 별도 기사 「스코프」에서 다룹니다.

여기서 언급한 한계점들은 결함에 대한 고발이 아닙니다. 빠르게 움직이는 구현(Implementation)과, 이를 따라잡는 과정에 있는 코멘트·타입(Type)·문서 사이의 현재 격차를 의미합니다. 도입 판단 실무에 적용하면 다음과 같이 읽을 수 있습니다.

• 조언에 그치는 검증(센서·리뷰어)에 '자동으로 차단하는 문(Gate)'을 기대하지 마십시오. 차단하는 것은 승인 게이트(Approval Gate)뿐입니다.
• 타입(Type)으로 존재하는 기능(dispatch-subagent / present-gate)을 '사용 가능하다'고 전제하지 마십시오.
• core/의 코멘트나 개략적인 산문을 확정된 사양으로 맹신하지 말고, 필요하다면 실체를 직접 세어보십시오.

도입 여부 자체를 어떻게 구성할지는 별도 기사 「도입 판단」에서, 전체적인 지도는 별도 기사 「개념 맵」에서 다룹니다.

파일	내용
core/sensors/	센서 4개. 모두 default_severity: advisory
core/hooks/aidlc-sensor-fire.ts	트리거 후크(Fire hook). "always exit 0", "Blocking … defer to the future ralph driver"
core/tools/aidlc-sensor.ts	판정 진리표(8행·도달 7행). FAILED는 1행뿐이며 나머지는 PASSED. "Sensor outcomes are advisory"
core/aidlc-common/protocols/stage-protocol.md	승인 게이트가 유일한 정지점, §12a 리뷰어는 "Does not block", §13 학습 게이트는 "it never blocks the gate", §8 스코프 표
core/tools/aidlc-state.ts	페이즈 경계에서 PHASE_VERIFIED를 무조건 발행, 합격/불합격 필드 없음
core/tools/aidlc-directive.ts	9종의 지시(Directive) 판별 공용체(parked 포함)
core/tools/aidlc-orchestrate.ts	7종의 발행과, 제외(omit)되는 dispatch-subagent / present-gate (later waves)
core/tools/aidlc-graph.ts	docstring은 "31 stage files" (실체는 32개). SCOPE_PRIORITY의 4계층 체인 (stage 계층 없음)
core/aidlc-common/stages/	스테이지 정의 실체 32개. 각 scopes: 프론트매터(Frontmatter)의 스코프별 집계
core/scopes/aidlc-enterprise.md / aidlc-feature.md	"enterprise가 전체 32회 실행의 유일한 것"이라는 기술과 "feature도 전체 32회 실행"이라는 산문의 모순
core/knowledge/aidlc-shared/rules-reading.md	이용 가이드에 {{HARNESS_DIR}}/rules/ 및 "5계층"을 기술 (코드는 core/memory/의 4계층)

이전 기사: 상태와 감사

다음 기사: 도입 판단

목차: AI로 풀어보는 AI-DLC v2