8장 §2

생애주기 관리

에이전트, 스킬, 스크립트 각각이 생성부터 폐기까지 어떤 단계를 거치는지, 그리고 이 단계들이 실제 워크스페이스에서 어떻게 관리되는지 다룬다.

이 절에서 다루는 것

에이전트 생애주기: create → verify → operate → improve → deprecate
스킬 생애주기: define → test → deploy → version → retire
스킬 관계 그래프: 스킬 관계를 생성 투영으로 관리하는 방법
스크립트 생애주기: write → lint → test → register → deprecate
상태(State)와 생애주기(Lifecycle)의 구분
생애주기 관리가 왜 필요한지

생애주기 관리가 필요한 이유

멀티 에이전트 시스템을 운영하다 보면 워크스페이스에 에이전트, 스킬, 스크립트가 계속 늘어난다. 새로운 것을 만드는 것만으로는 충분하지 않다. 각 구성요소가 어떤 단계에 있는지를 명확히 해야 한다. 그래야 다음 문제들을 피할 수 있다.

미검증 구성요소가 운영에 투입되는 문제. 에이전트가 agent:verify를 거치지 않고 배포되면, 누락된 프론트매터 필드나 잘못된 역할 정의로 인해 실제 세션에서 에러가 발생한다.
폐기 대상이 여전히 호출되는 문제. 더 이상 유효하지 않은 스킬이 레지스트리에 남아 있으면, 에이전트가 의도치 않게 해당 스킬을 선택하고 실패한다.
버전 불일치로 인한 재현 불가 문제. 스크립트가 갱신되었는데 어떤 variant에서는 구버전을 여전히 참조하고 있으면, 동일한 입력에 대해 다른 결과가 나온다.

이러한 문제를 체계적으로 방지하기 위해, ai-workspace-standards는 에이전트·스킬·스크립트 각각에 대해 명명된 단계(named stages)를 정의하고, 각 단계에서 수행해야 하는 검증과 전이 조건을 규정한다. 이 절에서는 세 가지 생애주기를 각각 설명하고, 워크스페이스에서 실제로 어떻게 관리되는지를 다룬다.

에이전트 생애주기

에이전트는 agents/ 디렉터리 아래에 .md 파일로 정의된다. 에이전트 하나가 태어나서 운영되다가 결국 폐기되기까지 다음 다섯 단계를 거친다.

Create — 에이전트 생성

에이전트 생애주기는 agents/ 디렉터리에 새 .md 파일을 만드는 것으로 시작된다. 이 파일에는 프론트매터(name, role, model 등 필드)와 본문(system prompt)이 포함된다. 생성 시 다음 사항을 확인한다.

파일명이 에이전트 역할을 명확히 나타내는지(예: pm.md, reviewer.md)
프론트매터에 name, role, model, status 필드가 모두 있는지
본문에 해당 에이전트의 동작 원칙과 제약 조건이 명시되어 있는지

초기 status 필드값은 draft로 설정한다. 이 상태에서는 에이전트가 운영 세션에서 자동으로 선택되지 않는다.

Verify — 에이전트 검증

생성된 에이전트 파일이 워크스페이스 규격에 맞는지 bun run agent:verify로 검증한다. 이 명령은 다음을 확인한다.

프론트매터 필드 누락 여부 및 타입 일치 여부
AGENTS.md에 해당 에이전트가 올바르게 등록되어 있는지
참조하는 스킬과 스크립트가 실제 존재하는지
다른 에이전트와 역할이 중복되지 않는지

검증을 통과하면 status를 active로 변경한다. 통과하지 못하면 draft 상태를 유지하며, 에러 메시지를 기준으로 수정 후 재검증한다.

Operate — 에이전트 운영

active 상태의 에이전트는 실제 세션에서 호출될 수 있다. 운영 단계에서는 에이전트의 실제 동작을 관찰하고, 세션 로그에서 다음을 모니터링한다.

에이전트가 정의된 역할에 맞게 동작하는지
다른 에이전트와의 협업에서 간섭이나 충돌이 없는지
응답 품질이 기대 수준에 도달하는지

운영 중 발견된 문제는 기록하여 Improve 단계의 입력으로 사용한다.

Improve — 에이전트 개선

운영 피드백을 바탕으로 에이전트 파일을 갱신한다. 개선 내역은 다음과 같다.

system prompt의 모호한 지시를 명확하게 수정
누락된 제약 조건이나 예외 처리 규칙 추가
모델 변경(model 필드)이 필요한 경우 갱신

파일을 수정한 후에는 반드시 다시 bun run agent:verify를 실행하여 재검증해야 한다. Verify 단계로 돌아가는 이 루프는 에이전트 생애주기에서 핵심적인 피드백 사이클이다. 검증을 통과하면 다시 Operate 단계로 진입한다.

Deprecate — 에이전트 폐기

에이전트가 더 이상 필요하지 않게 되면 status를 deprecated로 변경한다. 폐기 시 다음을 수행한다.

AGENTS.md에서 해당 에이전트 항목을 제거하거나 주석 처리
해당 에이전트를 참조하던 variant나 스크립트에서 의존성 제거
파일 자체는 삭제하지 않고 status: deprecated로 보존(필요 시 복원 가능)

일정 기간(예: 30일)이 지난 후, 더 이상 참조가 없는 것으로 확인되면 파일을 아카이브 디렉터리로 이동하거나 최종 삭제한다.

bun run agent:verify는 에이전트 생애주기에서 Verify 단계의 핵심 도구다. 이 명령은 단순한 문법 검사를 넘어, 에이전트가 워크스페이스의 다른 구성요소와 일관성 있게 연결되어 있는지까지 확인한다. CI/CD 파이프라인에 이 검증을 포함시키면, 미검증 에이전트가 운영에 투입되는 것을 시스템적으로 방지할 수 있다.

스킬 생애주기

스킬은 에이전트가 세션에서 호출할 수 있는 재사용 가능한 동작 단위다. SKILL.md 파일로 정의되며, 플러그인이나 워크스페이스의 .claude/skills/에 배치된다. 스킬의 생애주기는 다음 다섯 단계로 구성된다.

Define — 스킬 정의

스킬은 SKILL.md 파일로 정의된다. 이 파일에는 프론트매터(name, description, triggers 등)와 함께 스킬이 수행할 동작의 설명이 포함된다. 정의 시 다음을 명확히 한다.

name: 스킬의 고유 식별자
description: 에이전트가 이 스킬을 언제 선택해야 하는지를 결정하는 설명
triggers: 스킬이 자동으로 활성화되는 조건
본문: 스킬 실행 시 에이전트가 따라야 할 절차

초기에는 status: draft로 두고, 에이전트가 실제로 이 스킬을 자동 선택하지 못하게 한다.

Test — 스킬 검증

스킬 정의가 올바른지 validate-skills.ts로 검증한다. 이 스크립트는 다음을 확인한다.

프론트매터 필드 완전성 및 형식 일치
트리거 조건이 다른 스킬과 모호하게 겹치지 않는지
참조하는 도구(MCP tool 등)가 현재 환경에서 사용 가능한지
스킬 설명이 에이전트가 올바르게 이해할 수 있는 수준으로 구체적인지

검증을 통과하면 Deploy 단계로 이동할 준비가 된다.

Deploy — 스킬 배포

검증된 스킬을 에이전트가 실제로 호출할 수 있는 환경에 배포한다. 배포란 구체적으로 다음을 의미한다.

status를 active로 변경하여 에이전트의 자동 선택 대상에 포함
필요한 경우 워크스페이스의 .claude/skills/ 또는 플러그인 레지스트리에 등록
해당 스킬을 사용하는 에이전트의 프론트매터에 의존성을 명시

배포 후에는 에이전트 세션에서 스킬이 정상적으로 트리거되고 실행되는지 확인하는 수동 검토를 수행한다.

Version — 스킬 버전 관리

운영 환경에서 사용 중인 스킬에 변경이 필요할 때 버전 관리를 통해 안전하게 갱신한다.

스킬 파일의 변경 이력을 SKILL.md 헤더 주석이나 changelog에 기록
호환성을 깨뜨리는 변경(breaking change)인 경우, 기존 스킬을 유지한 채 새 버전으로 복제 후 갱신
변경 후 반드시 validate-skills.ts로 재검증을 수행

Version 단계에서 Test 단계로 돌아가는 루프는 스킬 생애주기의 핵심 피드백 사이클이다. 갱신된 스킬이 검증을 통과하면 다시 Deploy 단계로 진입한다.

Retire — 스킬 폐기

스킬이 더 이상 사용되지 않거나 다른 스킬로 대체되면 폐기한다.

status를 retired로 변경하여 에이전트 선택 대상에서 제외
해당 스킬을 참조하던 에이전트의 프론트매터에서 의존성 제거
파일은 보존하되 retired 상태로 명시하여 재사용 시 원본 참조 가능하게 유지

validate-skills.ts는 스킬 생애주기에서 Test 단계의 핵심 도구다. 이 스크립트는 단순한 형식 검사뿐 아니라, 스킬 간 트리거 충돌과 참조 무결성까지 점검한다. 새 스킬을 추가하거나 기존 스킬을 수정할 때마다 반드시 실행해야 한다. 에이전트의 agent:verify와 마찬가지로, CI/CD 파이프라인에 포함시키면 미검증 스킬의 배포를 자동으로 방지할 수 있다.

스킬 관계 그래프

스킬이 늘어나면 개별 스킬의 품질만큼 중요해지는 것이 스킬 사이의 관계다. 어떤 스킬이 먼저 실행되어야 하는지, 어떤 스킬이 함께 쓰이는지, 어떤 에이전트가 어떤 스킬을 사용하는지 — 이런 정보를 사람이 문서로 유지하면 금방 낡아 버린다. 스킬 관계 그래프는 이 문제를 "직접 쓰지 않고 기계가 읽을 수 있는 원천에서 항상 다시 생성하는" 방식으로 해결한다(ADR-0060, Skill Relationship Graph as Generated Projection).

핵심 원칙 — 그래프는 1차 저장소가 아니라 생성물

그래프 파일(docs/skill-graph.json, docs/skill-graph.md)은 빌드 아티팩트다. 관계의 원천(source of truth)은 다음과 같은 기존 데이터이며, 그래프는 이를 항상 다시 유도(re-derive)할 수 있는 투영(projection)이다.

SKILL.md 프론트매터 — prerequisites, 타입화된 relates_to
에이전트 파일의 required_skills
variant.json의 skill_manifest
문서 본문의 백틱 참조(정확 일치)
docs/skill-graph.overrides.json — 유도 불가능하거나 억제할 관계용 탈출구

이 원칙 덕분에 그래프는 낡지 않는다. 생성 스크립트를 다시 실행하면 언제나 현재 상태의 그래프를 얻고, 결정론성 검증으로 같은 입력이 같은 출력을 내는지 확인한다.

노드와 관계(엣지) 타입

노드는 skill, agent, adr, decision, procedure, output_type 등의 타입을 가지며, 계층(L0 워크스페이스 루트, common, variant:<name>, L3 프로젝트)으로 표시된다. 주요 엣지 타입은 다음과 같다. 모든 엣지는 자문적(advisory)이라 실행을 강제로 막지는 않는다.

엣지	의미
`requires`	B는 A의 필수 선행 스킬이다(프론트매터 `prerequisites`에서 유도)
`relates_to`	일반적 연관(레거시)
`composes_with`	대칭적 조합 관계(`symmetric: true`로 단일 엣지 저장)
`follows`	순서만 나타내며 의존성을 함축하지 않음
`enables`	A의 산출물이 C를 가능하게 함
`used_by` / `phase`	에이전트가 스킬을 사용함 / 스킬이 워크플로우 단계에 배속됨
`supersedes` / `references` / `cites_skill`	문서 계승, 문서 간 인용, 의사결정 기록의 스킬 인용

관계의 3계층 모델

L-A 명시적(Explicit) — 프론트매터의 타입화된 relates_to. 의도상 영구적이며 1차 원천이다.
L-B 실험적(Experimental) — 오버라이드 파일의 관계. 필수로 reason/since를 기록하며 90일이 지나면 낡음 경고가 뜬다.
L-C 투영(Projection) — 생성된 그래프 JSON. 항상 재생성되며 결정론성이 검증된다.

도구와 파이프라인 통합

scripts/generate-skill-graph.ts — SSOT 원천을 훑어 그래프를 생성한다. --scope <name>으로 템플릿별 범위 그래프를 만든다.
scripts/verify-skill-graph.ts — 커밋된 그래프가 원천과 일치하는지 드리프트 검증.
dev-sync.ts(동기화 파이프라인 4.65단계) — 매 /sync마다 모든 범위의 그래프를 재생성하고 검증한다.
new-project.ts(스캐폴딩 7.6단계) — 새 프로젝트 생성 시점에 그래프를 즉시 생성한다.

관계를 문서가 아니라 데이터로 두는 이 사고방식은 이 교재 전반의 SSOT 원칙과 같은 뿌리다. "사람이 목록을 고치는" 조직은 목록이 반드시 낡지만, "데이터에서 유도되는 목록"은 재생성으로 항상 최신을 유지한다. 두 가지 구축 전략이 비교 실험되었는데 — 프론트매터에 직접 선언하는 선언적(Declarative) 전략과, 기존 구조화 데이터(절차 스키마 등)에서 관계를 유도하는 추론적(Inferential) 전략이다. 비교 결과 절차 스키마가 풍부한 영역에서는 추론이 잘 동작했지만, 그렇지 않은 템플릿에서는 선언적 전략이 더 낫다는 결론으로 새로운 기본 추출 모드는 채택되지 않았다.

스크립트 생애주기

스크립트는 scripts/ 디렉터리 아래에 .ts 파일로 관리된다. 에이전트 생성 검증, 템플릿 발행, 프로젝트 스캐폴딩 등 워크스페이스 인프라를 자동화하는 실행 가능한 코드다. 스크립트의 생애주기는 다음 다섯 단계로 구성된다.

Write — 스크립트 작성

새 스크립트는 scripts/ 디렉터리에 .ts 파일로 작성된다. 작성 시 다음을 준수한다.

파일명이 스크립트의 목적을 명확히 나타내야 한다(예: propagate-to-templates.ts, validate-skills.ts)
스크립트 상단에 목적, 사용법, 인자 설명을 주석으로 기록
타입 정의를 명확히 하고, 외부 의존성을 최소화
에러 처리를 포함하여 실패 시 의미 있는 메시지를 출력

작성 직후의 스크립트는 draft 상태로 간주한다.

Lint — 정적 분석

작성된 스크립트에 대해 정적 분석(lint)을 수행한다. TypeScript 기반 워크스페이스에서는 bun run lint 또는 tsc --noEmit를 사용하여 다음을 확인한다.

타입 오류 없음
사용되지 않는 변수나 임포트 없음
코드 스타일 일관성
잠재적 런타임 에러(예: null 참조) 경고

정적 분석에서 발견된 문제는 모두 수정해야 다음 단계로 진행할 수 있다.

Test — 테스트

정적 분석을 통과한 스크립트에 대해 단위 테스트 및 통합 테스트를 수행한다. 스크립트가 파일 시스템이나 네트워크에 의존하는 경우, 모의(mock) 환경에서 테스트한다.

정상 경로(happy path): 예상 입력에 대해 올바른 출력이 나오는지
예외 경로: 잘못된 입력, 파일 없음, 권한 오류 등에 대해 적절히 에러를 처리하는지
통합 테스트: 실제 워크스페이스 환경에서 다른 스크립트나 에이전트와 연동 시 정상 동작하는지

테스트를 통과한 스크립트만 Register 단계로 이동할 수 있다.

Register — 스크립트 등록

테스트를 통과한 스크립트를 package.json의 scripts 섹션에 등록하여 bun run <name> 형태로 실행할 수 있게 만든다.

package.json에 적절한 스크립트 이름과 실행 명령을 추가
스크립트 설명서(이 핸드북 또는 별도 README)에 사용법을 기록
다른 스크립트나 에이전트에서 이 스크립트를 호출하는 경우, 해당 의존성을 문서화

등록 완료 후, bun run <name>가 정상적으로 실행되는지 최종 확인한다.

Deprecate — 스크립트 폐기

스크립트가 더 이상 필요하지 않거나 다른 스크립트로 대체된 경우 폐기한다.

package.json에서 해당 스크립트 항목을 제거
이 스크립트를 호출하던 다른 스크립트에서 의존성을 제거하고 대체 경로로 업데이트
파일 자체는 scripts/_deprecated/ 같은 아카이브 디렉터리로 이동하거나, 주석에 @deprecated를 명시하여 보존

스크립트 생애주기에서 사람이 직접 수행하는 수동 검토(manual review)는 Lint와 Test 사이, 그리고 Test와 Register 사이에서 각각 한 번씩 권장된다. 자동화된 검증이 모든 문제를 잡을 수는 없다. 특히 스크립트가 워크스페이스의 파일 구조를 변경하는 경우(예: propagate-to-templates.ts), 사람이 실제 결과를 눈으로 확인하는 과정이 필수적이다.

세 생애주기의 공통 원칙과 상호 의존성

상태(State)와 생애주기(Lifecycle)의 구분

지금까지 세 종류의 생애주기를 파이프라인으로 설명했다. 여기서 헷갈리지 않아야 할 구분이 하나 있다 — 생애주기(lifecycle)와 상태(state)는 다른 개념이다.

생애주기는 구성요소가 거치는 순차적 단계 전체를 말한다. 에이전트라면 Create → Verify → Operate → Improve → Deprecate의 5단계 파이프라인 자체가 생애주기다.
상태는 특정 시점에 그 구성요소가 어디에 있는지를 나타내는 스냅샷이다. YAML frontmatter의 status 필드(draft, active, deprecated, retired)가 바로 이 상태 값을 저장하는 메커니즘이다.

비유하면 생애주기는 "지하철 노선도"이고 상태는 "현재 열차가 어느 역에 있는지"를 보여주는 실시간 표시판이다. 열차가 어디로 가야 하는지(노선)는 고정되어 있지만, 지금 어디에 있는지(역)는 시시각각 변한다.

워크플로우 실행 차원의 상태 — 예를 들어 PM이 9장에서 정의하는 Phase Pipeline(Phase 0: 요청 수신 → Phase 1: 설계 → … → Phase 6: 동기화 완료) — 은 개별 구성요소의 status 필드와는 또 다른 차원의 상태다. 전자는 "작업이 어느 단계에 있는가"이고, 후자는 "이 구성요소 자체가 생애주기의 어디에 있는가"이다.

에이전트·스킬·스크립트의 생애주기는 각각 독립적으로 정의되어 있지만, 실제 워크스페이스에서는 밀접하게 연결되어 있다.

검증 도구	관련 생애주기	역할
`bun run agent:verify`	에이전트	에이전트 파일의 구조, 참조 무결성, AGENTS.md 등록 여부 검증
`validate-skills.ts`	스킬	스킬 프론트매터, 트리거 충돌, 도구 참조 유효성 검증
수동 검토	모든 생애주기	자동 검증으로 잡히지 않는 의미적 정확성, 사용성, 영향 범위 확인

세 생애주기는 다음 세 가지 공통 원칙을 공유한다.

단계 명시: 모든 구성요소는 status 필드나 파일 위치를 통해 현재 단계를 명확히 나타내야 한다. draft 상태인 것은 운영에 투입되지 않으며, deprecated/retired 상태인 것은 새로운 호출 대상에서 제외된다.
검증 게이트: 한 단계에서 다음 단계로 이동하기 전에 반드시 정의된 검증을 통과해야 한다. 검증에 실패하면 이전 단계로 돌아가서 수정 후 재검증한다.
폐기 후 보존: 폐기된 구성요소를 즉시 삭제하지 않고 일정 기간 보존한다. 이를 통해 필요한 경우 복원이 가능하고, 폐기 결정의 근거를 추적할 수 있다.

다음 절(§3 아키텍처 심화)에서는 생애주기 관리 원칙이 실제 고도화 방향(컨테이너화, 메모리 관리, variant 배포 파이프라인)과 어떻게 결합되는지를 다룬다.

참고 영상

ENWhy AI Agents Need a Lifecycle(6:49) — AI 에이전트 생애주기 관리의 필요성과 기업이 놓치는 관리 포인트
ENThe Agent Development Lifecycle (ADLC)(5:22) — 신뢰할 수 있는 AI 에이전트 출시를 위한 체계적 블루프린트
KOAI 에이전트 엔지니어링 | 2강. 에이전트 시스템 설계(35:21) — 에이전트 시스템의 구조와 설계 방식을 다루는 생애주기 핵심 강의

← 이전

8장 §1 · 배포와 SSOT

8장 §3 · AGENTS.md 심화