본 기사의 위치 — 본 기사는 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) 입니다. 현재 공정의 어디까지 진행되었는지를 기록한 현재 위치의 스냅샷으로, 보고할 때마다 덮어쓰기 됩니다. 다른 하나는 감사 로그 (Audit) 입니다. 무엇이 언제 일어났는지를 지우지 않고 쌓아가는, 추가 전용 이력입니다. "지금 어디에 있는가"와 "어떻게 왔는가"를 서로 다른 파일이 담당하므로, 대화가 끊기거나 문맥이 압축되더라도 다른 대화에서 이어서 재개할 수 있습니다.

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

엔진이 매번 다시 읽는 것

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

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

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

상태 파일

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

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

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

마지막 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) 합니다 (파일의 연결 순서가 곧 최신성을 의미하지 않는다는 점에 주의하십시오). 샤드 자체는 버전 관리 (commit 대상) 대상이며, gitignore 되는 것은 per-user 커서나 clone-id, runtime-graph 등 기계 고유의 것들뿐입니다. 또한 병행 쓰기는 intent 단위의 감사 락 (audit lock)으로 직렬화되지만, stale-lock 회수에는 구현 코멘트에서 인정하는 잔존 레이스 (race condition)가 존재합니다 (별도 기사 「한계와 주의점」에서 다룹니다).

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

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

또한,

• 도구가 작성함 — 상태 전이에 따른 이벤트. 스테이지의 시작·완료·게이트의 승인/반려·워크플로 완료 등은 aidlc-state.ts가, 사람에 대한 질문·답변은 aidlc-log.ts가, Construction의 Bolt는 aidlc-bolt.ts가 각각 상태를 변경함과 동시에 대응하는 감사(Audit) 이벤트를 발생(emit)시킵니다.
• 훅(Hook)이 작성함 — 대화 흐름에 결합된 이벤트. 산출물 파일의 생성·갱신(ARTIFACT_CREATED / ARTIFACT_UPDATED)은 PostToolUse 훅이, 서브 에이전트의 완료(SUBAGENT_COMPLETED)는 전용 훅이, 세션의 시작·종료·컴팩션(SESSION_*)은 라이프사이클 훅이 포착합니다.

감사의 각 이벤트에는 '발생원(emitter)'이 정해져 있으며, 도구 발생과 훅 발생이 혼재합니다. 예를 들어 STAGE_COMPLETED는 aidlc-state.ts의 approve / advance로부터, ARTIFACT_CREATED는 훅으로부터 발생하는 것처럼, 누가 발생시키느냐가 고정되어 있습니다.

컨덕터(Conductor)가 건드리지 않는 설계상의 예외가 딱 하나 있습니다. 바로 memory.md(학습 로그)입니다. state와 audit이 도구에 맡겨져 있는 반면, memory.md만은 컨덕터가 판단을 직접 수기로 기록하는 유일한 파일입니다. 이 대비는 별도의 기사 「학습 루프」에서 다룹니다.

세션을 넘나드는 재개

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

시작 시. SessionStart 훅은 세션이 시작되는 방식(source)을 이벤트로 변환합니다. startup과 clear는 SESSION_STARTED로, resume은 SESSION_RESUMED로 변환됩니다. 단, compact(컴팩션 후의 재개) 시에는 아무것도 발생시키지 않습니다. 컴팩션 자체는 직전에 다른 훅이 기록했으므로, 중복 기록 시 이력이 혼탁해지기 때문입니다. 또한 이 훅은 상태 파일을 읽어 현재의 페이즈(Phase)·스테이지(Stage)·상태(Status)·다음 액션(Action)을 엔진에 문맥(Context)으로 주입하여 재개를 돕습니다. 상태 파일이 없다면(=진행 중인 워크플로가 없다면) 아무것도 하지 않습니다.

컴팩션 직전. PreCompact 훅이 상태 파일의 타당성을 확인합니다. 필수 섹션(## Stage Progress와 ## Current Status)이 갖춰져 있는지 검증하고, .aidlc-recovery.md라는 브레드크럼(Breadcrumb)을 남긴 뒤, SESSION_COMPACTED(현재 스테이지와 타당성 판정 포함)를 발생시킵니다. 압축으로 인해 문맥이 손실되기 직전에 현재 위치의 스냅샷이 손상되지 않았는지 점검하는 구조입니다.

종료 시. SessionEnd 훅이 SESSION_ENDED를 발생시킵니다. 세션의 종료가 워크플로의 완료는 아닙니다. 양자의 라이프사이클은 독립적이며, 이 이벤트는 어디까지나 관측용입니다. 대화가 끊겨도 워크플로는 중단되었을 뿐이며, 상태 파일은 남아 다음번에 그 지점부터 재개할 수 있습니다.

재개 시에는 상태 도구의 resume(읽기 전용)이 감사 로그의 끝을 확인하여,

| 상태 (state) | 감사 (audit) |
|---|---|---|
| 보유하는 것 | 현재 위치 | 이력 |
| ... |

현재 위치를 알기 위해 과거의 모든 이벤트를 재생할 필요는 없습니다. 그렇기에 state는 한 지점에 덮어쓰며 가볍게 유지합니다. 반대로, 경위를 추적하기에는 한 지점만으로는 부족합니다. 그렇기에 audit은 아무것도 버리지 않고 쌓아 올립니다. "지금 어디인가"와 "어떻게 왔는가"는 별개의 질문이며, 별개의 파일이 답합니다. 이 역할 분담이 기억을 갖지 않는 엔진이 매번 현재 위치를 다시 읽을 수 있게 하고, 동시에 나중에 모든 공정을 감사할 수 있도록 만듭니다.

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

참조 원천

관련 기사

이전 기사: 학습 루프

다음 기사: 한계와 주의점

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

Discussion