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

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

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

진행을 관장하는 엔진은 상태(State, 기억)를 가지지 않습니다. 그렇기 때문에 "다음에 무엇을 할지"를 판단할 때마다 외부 파일을 다시 읽습니다. AI-DLC v2가 그 근거로 삼는 것은 성질이 정반대인 두 개의 파일입니다. 하나는 상태 (State) 입니다. 현재 공정의 어디까지 진행되었는지를 기록한 현재 위치의 스냅샷(Snapshot)으로, 보고할 때마다 덮어쓰기 됩니다. 다른 하나는 감사 로그 (Audit) 입니다. 무엇이 언제 일어났는지를 지우지 않고 쌓아 올리는, 추가 전용(Append-only) 이력입니다. "지금 어디에 있는가"와 "어떻게 왔는가"를 별개의 파일이 담당하기 때문에, 대화가 끊기거나 문맥이 압축되더라도 다른 대화에서 이어서 재개할 수 있습니다.

본 기사에서는 이 두 가지가 각각 무엇을 어떻게 가지는지, 누가 작성하는지, 세션을 넘어 어떻게 재개를 지원하는지, 그리고 왜 역할을 두 개로 나누는지에 대해 풀어봅니다.

AI-DLC v2의 워크플로우(Workflow)는 하나의 대화(세션) 안에서만 완결되는 것은 아닙니다. 도중에 대화가 끊기거나, 컴팩션(Compaction)으로 문맥이 압축되더라도 다른 날에 이어서 재개할 수 있습니다. 그것을 뒷받침하는 것이 두 개의 파일입니다.

• 상태 파일 (State) — 현재 어디까지 진행되었는지를 기록한 현재 위치의 스냅샷. 보고할 때마다 덮어쓰기 된다.
• 감사 로그 (Audit) — 무엇이 언제 일어났는지를 나열한, 지우지 않고 쌓아 올리는 이력.

진행을 관장하는 엔진은 상태를 가지지 않습니다. 그래서 매번 이 상태 파일을 다시 읽어 "다음은 무엇인가"를 판단합니다. 왜 엔진이 상태를 가지지 않는 설계인지, 그 이유와 엔진 본체의 메커니즘은 별도 기사인 「진행의 핵심」에서 다룹니다. 이 기사는 그 한 단계 아래인, state와 audit이 "무엇"을 어떻게 가지고 있는가에 집중합니다.

상태는 <record>/aidlc-state.md라는 마크다운(Markdown) 파일 한 장입니다 (<record> = 액티브 인텐트(Active intent)의 기록 디렉토리 aidlc/spaces/<space>/intents/<YYMMDD>-<label>/. 단일 팀이라면 spaces/default/). 보고할 때마다 툴(Tool)이 덮어쓰기 하므로 이력은 남기지 않습니다. 항상 "지금 이 순간"만을 기록합니다. 파일로 남기 때문에 대화를 넘나들어도, 혹은 다른 대화에서라도 이곳을 읽으면 현재 위치를 알 수 있습니다.

서두의 Project Information 절에는 State Version: 7이 기재되어 있습니다. 이는 상태 파일의 스키마(Schema) 버전 번호로, 절(Section)이나 필드(Field)의 구성이 바뀔 때마다 올라갑니다. 오래된 버전의 상태 파일을 새로운 툴이 읽을 때 발생하는 불일치를 감지하기 위한 표식입니다.

파일은 9개의 절(## 헤더)로 구성되어 있습니다.

절	역할
Project Information	프로젝트 개요·종별(Greenfield/Brownfield)·스코프(Scope)·시작 일시·State Version·현재의 리드 에이전트(Lead agent) 등
...	진행 상황은 두 가지 입도로 기록합니다. Phase Progress는 페이즈(Phase) 전체를 Pending / Active / Verified / Skipped의 4가지 상태로 거칠게 나타내며, Stage Progress는 각 스테이지(Stage)를 체크박스로 세밀하게 추적합니다. 체크박스는 6가지 상태가 있습니다.

표기	의미
[ ]	미착수
[-]	진행 중 (현재 스테이지, 아직 승인 전)
[?]	승인 대기 (게이트가 열려 있음)
[R]	개정 중 (사람이 반려함)
[x]	완료 (사람이 승인함)
[S]	스킵 (스코프 제외, skip, --stage / --phase 점프를 통한 우회)

마지막 Session Resume Point 절은 재개를 위한 발판입니다. "마지막으로 완료한 스테이지", "다음에 할 일", "미완성된 결과물"을 적어두어, 재개 시 이곳에서 문맥을 다시 세웁니다.

스코프와 깊이 (Scope Configuration / Depth)가 상태 파일에 유지된다는 점은 각각 별도의 기사 「스코프」와 「깊이」에서 다룹니다. 본 기사에서는 "상태 파일에 존재한다"는 점만 언급합니다.

보충: 스테이지 프로토콜 (stage-protocol.md §4)의 표기 일람은

[ ] / [-] / [x] / [S]

의 4개로 생략되어 있지만, 상태 파일의 템플릿과 상태 도구의 구현은 모두 위의 6가지 상태를 가집니다. 본 기사는 템플릿과 구현을 우선하여 6가지 상태로 기술하고 있습니다.

감사 로그 (Audit Log)는 기록 디렉토리 하위에 존재합니다. 상태 파일이 "덮어쓰기 되는 현재 위치"라면, 이것은 정반대로 추가 전용·변경 금지의 이력입니다. 한 번 작성된 엔트리는 절대 다시 쓰거나 지우지 않고, 오직 끝에 쌓아 올립니다. 사람의 판단(승인 한마디 등)은 요약하지 않고 축자적으로 남깁니다. 나중에 "언제·무엇이 일어났고, 왜 그렇게 결정했는가"를 다시 추적하기 위한 기록이기 때문입니다.

감사 로그는 클론별 샤드 (Shard) <record>/audit/<host>-<clone-id>.md>

로 나뉩니다 (clone-id는 gitignore 처리된 aidlc/.aidlc-clone-id의 안정적인 12자리 토큰). 여러 클론이나 워크트리 (worktree)가 병행하여 작성하더라도 이력 (trail)이 충돌 (merge-conflict)하지 않도록 설계된 것입니다. 읽는 쪽은 <record>/audit/*.md를 glob 처리하여 타임스탬프 기준으로 시계열 병합 (merge) 합니다 (파일의 연결 순서가 곧 최신성을 의미하지 않는다는 점에 주의하십시오). 샤드 자체는 버전 관리 (커밋 대상) 대상이며, gitignore 되는 것은 사용자별 커서나 clone-id, runtime-graph 등 기계 고유의 것들뿐입니다. 또한 병행 쓰기는 intent 단위의 감사 락 (audit lock)으로 직렬화되지만, stale-lock 회수에는 구현 코멘트에서 인정하는 잔존 레이스 (race)가 존재합니다 (별도 기사 「한계와 주의점」에서 다룹니다).

이벤트에는 명명 규칙이 있습니다. 모두 SUBJECT_PAST_VERB, 즉 과거형으로 "무엇이 일어났는가"에 답하는 형태 (STAGE_COMPLETED, GATE_APPROVED 등)입니다. 그리고 등록된 이벤트는 69종, 18개 카테고리로 정리되어 있습니다 (WORKFLOW_PARKED / WORKFLOW_UNPARKED 등을 포함합니다).

카테고리	주요 이벤트 예시
Workflow Lifecycle	WORKFLOW_STARTED / WORKFLOW_COMPLETED / WORKFLOW_PARKED / WORKFLOW_UNPARKED
Phase Lifecycle	PHASE_STARTED / PHASE_COMPLETED / PHASE_VERIFIED
Stage Lifecycle	STAGE_STARTED / STAGE_COMPLETED / STAGE_SKIPPED
Session Events	SESSION_STARTED / SESSION_RESUMED / SESSION_COMPACTED / SESSION_ENDED
Initialization	WORKSPACE_SCAFFOLDED / WORKSPACE_INITIALISED
Navigation	SCOPE_CHANGED / DEPTH_CHANGED / SCOPE_DETECTED
Interaction	DECISION_RECORDED / GATE_APPROVED / GATE_REJECTED / QUESTION_ANSWERED
Artifact	ARTIFACT_CREATED / ARTIFACT_UPDATED / ARTIFACT_REUSED
Subagent	SUBAGENT_COMPLETED
Utility	HEALTH_CHECKED
Error/Recovery	ERROR_LOGGED / RECOVERY_COMPLETED
Construction Bolt	BOLT_STARTED / BOLT_COMPLETED / AUTONOMY_MODE_SET
Worktree	WORKTREE_CREATED / STATE_FORKED / AUDIT_MERGED
Practices	PRACTICES_DISCOVERED / PRACTICES_AFFIRMED
Merge Dispatch	MERGE_DISPATCH_INVOKED / MERGE_DISPATCH_FALLBACK
Sensor	SENSOR_FIRED / SENSOR_PASSED / SENSOR_FAILED
Learning Loop	MEMORY_EMPTY / RULE_LEARNED / SENSOR_PROPOSED
Swarm	SWARM_STARTED / SWARM_UNIT_CONVERGED / SWARM_COMPLETED

이 표는 각 카테고리의 대표 예시를 보여주며, 18개 카테고리 전체의 개요를 나타냅니다.

또 다른 규칙은

ツール가 작성하는 것 ― 상태 전이에 따른 이벤트.

스테이지의 시작/완료, 게이트 승인/반려, 워크플로우 완료 등은 aidlc-state.ts

사용자에게 질문/답변을 받는 것은 aidlc-log.ts

Construction의 Bolt는 aidlc-bolt.ts가 각각 상태를 갱신하는 동시에 대응하는 감사 이벤트(audit event)를 발생(emit)합니다. -
훅이 작성하는 것 ― 대화 흐름에 연결된 이벤트.
산출물 파일 생성/갱신(ARTIFACT_CREATED/ARTIFACT_UPDATED)은 PostToolUse 훅이, 서브 에이전트 완료(SUBAGENT_COMPLETED)는 전용 훅이, 세션의 시작/종료/압축(compact)(SESSION_*)은 라이프사이클 훅이 처리합니다.

감사 이벤트에는 '발생원(emitter)'이 정해져 있어, 도구 발생과 훅 발생이 혼재됩니다. 예를 들어 STAGE_COMPLETED는 aidlc-state.ts의 approve/advance에서, ARTIFACT_CREATED는 훅에서처럼, 누가 발생시킬지가 고정되어 있습니다.

컨덕터(conductor)가 건드리지 않는 설계상의 예외가 하나 있습니다. 바로 memory.md(학습 로그)입니다. state와 audit이 도구에 의존하는 것과 달리, memory.md만은 컨덕터가 판단을 직접 기록하는 유일한 파일입니다. 이 대비는 별도 글인 '학습 루프'에서 다루겠습니다.

재개(resume) 메커니즘은 3가지 라이프사이클 훅과 세션의 4가지 이벤트가 담당합니다.

시작 시. SessionStart 훅은 세션 시작 방식(source)을 이벤트로 변환합니다. startup과 clear는 SESSION_STARTED를, resume은 SESSION_RESUMED를 발생시킵니다. 다만 compact(압축 후 재개)에서는 아무것도 발생시키지 않습니다. 압축 자체는 직전에 다른 훅이 기록했기 때문에, 이중으로 기록하면 이력이 혼란스러워지기 때문입니다. 또한 이 훅은 상태 파일을 읽어 현재 페이즈, 스테이지, 상태, 다음 액션을 엔진에 문맥(context)으로 주입하여 재개를 돕습니다. 상태 파일이 없으면 (즉, 진행 중인 워크플로우가 없으면) 아무것도 하지 않습니다.

압축 직전. PreCompact 훅이 상태 파일의 유효성을 확인합니다. 필수 섹션(## Stage Progress와 ## Current Status)이 갖춰져 있는지 검증하고, .aidlc-recovery.md라는 흔적을 남기며, SESSION_COMPACTED(현재 스테이지 및 유효성 판정 포함)를 발생시킵니다. 이는 압축으로 문맥이 손실되기 직전에 현재 위치의 스냅샷이 손상되지 않았는지 점검하는 메커니즘입니다.

종료 시. SessionEnd 훅이 SESSION_ENDED를 발생시킵니다. 세션 종료가 워크플로우 완료는 아닙니다. 두 가지 생명주기는 독립적이며, 이 이벤트는 어디까지나 관측용입니다. 대화가 끊겨도 워크플로우는 중단된 것일 뿐이고, 상태 파일은 남아 다음번에 거기서 재개됩니다.

재개 시에는 상태 도구의 resume(읽기 전용)가 감사 로그의 끝을 보고,

그리고 두 가지 모두 도구(tool)와 후크(hook)가 작성합니다. 컨덕터(Conductor)는 현재 위치도 이력도 직접 건드리지 않습니다. 진행자는 판단에 전념하고, 기록은 메커니즘에 맡깁니다. — 이러한 분리가 AI-DLC v2의 진행 관리를 '재현 가능하고 감사 가능한' 것으로 만듭니다. 워크플로(workflow) 전체에서 이 두 가지가 어디에 위치하는지는 별도 기사 「공정과 에이전트」에서, 전체적인 조망은 별도 기사 「개념 맵」에서 다룹니다.

파일	내용
core/knowledge/aidlc-shared/state-template.md	상태 파일의 구조. State Version=7, 9개의 절, Phase Progress의 4가지 상태, Stage Progress의 6가지 상태 표기법, Session Resume Point
core/knowledge/aidlc-shared/audit-format.md	감사 이벤트의 택소노미 (taxonomy). 「69 events / 18 categories」의 Event Registry, SUBJECT_PAST_VERB 명명 규칙, 각 이벤트의 발생원, 추가 전용·축자(verbatim) 원칙
core/tools/aidlc-state.ts	상태의 읽기/쓰기 및 전이 (advance / approve / reject / skip / complete-workflow 등). VALID_CHECKBOX_STATES (6가지 상태), 전이와 동시에 감사 이벤트 발생
core/tools/aidlc-audit.ts	감사 로그의 추가. VALID_EVENT_TYPES (69종)에 의한 미등록 이벤트 거부, 추가 전용, CR/LF 이스케이프
core/hooks/aidlc-session-start.ts	세션 시작 후크 (session start hook). source → SESSION_STARTED / SESSION_RESUMED 변환 (compact는 발생하지 않음), 상태 파일의 컨텍스트 주입
core/hooks/aidlc-validate-state.ts	PreCompact 후크. 상태 파일의 타당성 검증, .aidlc-recovery.md 브레드크럼 (breadcrumb), SESSION_COMPACTED 발생
core/hooks/aidlc-session-end.ts	SessionEnd 후크. SESSION_ENDED 발생 (워크플로 완료와는 독립적인 관측용)
core/hooks/aidlc-audit-logger.ts	PostToolUse 후크. 기록 디렉토리 (<record>/)로의 쓰기를 ARTIFACT_CREATED / ARTIFACT_UPDATED로 발생
core/aidlc-common/protocols/stage-protocol.md	§4 State Tracking. 컨덕터 측의 절차, 「Event emission is tool-owned」(감사 추가는 도구의 몫)
CHANGELOG.md	버전 이력. 감사 택소노미가 버전을 거치며 69 events에 이르게 된 경위 (2.1.3의 WORKFLOW_PARKED / WORKFLOW_UNPARKED 추가 및 SWARM_* 추가 포함), 상태 전이 11개 서브 커맨드의 lost-update 안전화 (read → decide → audit → write를 감사 락(lock)으로 감싸는 방식)를 기재

이전 기사: 학습 루프

다음 기사: 한계와 주의점

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