일단, 이 글은 요즘 누구나 한번쯤 AI로 소프트웨어 제품 릴리즈 프로세스를 자동화하는 꿈(?)을 가지고 시도해봤을 법한 AI워크플로우 설계 작업에 관한 전반적인 내용을 “AI”와 함께 기록한 글이다.

글을 AI로 작성하는걸 딱히 좋아하진 않지만, 현 시점 AI가 자기 스스로 할 수 있는 일, 그리고 그에 맞춰본 나의 작업과 관점을 근미래에 되돌아보기 위해서 증적처럼 기록한다. (AI가 스스로의 일을 가장 자기참조적으로 잘 서술할 수 있다고 믿어본다.)

Claude Code로 AI Workflow 설계하기

Claude Code를 실제 개발 업무에 적용하다 보면 처음에는 대부분의 작업을 Skill로 만들게 된다.

요구사항을 분석하는 Skill, 기획하는 Skill, 디자인을 판단하는 Skill, 코드를 확인하는 Skill, 코드를 수정하는 Skill, PR을 만드는 Skill처럼 각각의 업무 단계를 프롬프트로 정의하고 순서대로 실행하는 방식이다.

하지만 workflow가 커질수록 새로운 문제가 생긴다.

각 단계에서 이전 단계의 대화와 코드 탐색 결과가 계속 누적되고, 하나의 Claude가 요구사항 분석부터 코드 수정과 배포 검증까지 모두 수행하게 된다. 결과적으로 context가 지나치게 커지고, 앞에서 했던 판단이나 탐색 과정이 뒤의 작업에 불필요하게 영향을 미치기 시작한다.

이 문제를 해결하기 위해서는 Skill을 더 잘 만드는 것만으로는 부족하다.

Skill, Agent, Hook, Context, Memory를 서로 다른 책임으로 분리하고, 각 단계 사이에 필요한 정보만 전달하는 구조가 필요하다.

요구사항 해석
    ↓
기획 판단
    ↓
디자인 판단
    ↓
코드 구현 가능성 판단
    ↓
코드 구현
    ↓
PR
    ↓
배포 검증
    ↓
릴리즈 게시

1. 먼저 Skill, Agent, Context, Memory를 분리해서 생각하기

Claude Code에서 Skill, Agent, Context, Memory는 모두 AI workflow를 구성하는 개념처럼 보이지만 역할과 동작 방식은 다르다.

가장 간단하게 정리하면 다음과 같다.

Memory
  ↓
장기 기억 : "다음에도 무엇을 기억해야 하는가?"

Context
  ↓
작업 기억 : "지금 무엇을 알고 있는가?"

Skill
  ↓
절차 기억 / 사고 방식 : "이 일을 어떻게 해야 하는가?"

Agent
  ↓
독립적인 작업자 : "이 일을 누가 수행할 것인가?"

Hook
  ↓
자동화된 시스템 규칙 : "이 조건이 발생하면 무엇을 강제할 것인가?"

1.1 CLAUDE.md는 어디에 속하는가

CLAUDE.md는 이 중 하나와 완전히 같은 레벨의 개념이라기보다 Context에 기본적으로 제공되는 프로젝트 맥락에 가깝다.

예를 들어:

현재 작업 Context

+ 현재 대화
+ CLAUDE.md
+ 읽은 파일
+ 실행한 Tool 결과
+ 활성화된 Skill
+ ...

따라서 CLAUDE.md는 “이 프로젝트에서 항상 알아야 하는 것”을 정의하는 장소라고 생각하면 된다.

2. Context와 Memory는 완전히 다르다

이 둘은 특히 혼동하기 쉽다.

Context

Context는

지금 이 순간 모델이 추론할 때 참고하는 정보

이다.

예를 들어 현재 Context에는 다음과 같은 정보가 들어올 수 있다.

현재 대화

CLAUDE.md

방금 읽은 파일

현재 활성화된 Skill

Tool 실행 결과

현재 작업의 요구사항

Context는 기본적으로 현재 작업을 위한 작업 기억이다.

따라서 context가 너무 커지면 중요한 정보와 중요하지 않은 정보가 같은 작업 공간에 섞이게 된다.

Memory

Memory는

현재 작업이 끝난 이후에도 다시 꺼내 쓸 수 있도록 보존되는 정보

에 가깝다.

예를 들어 장기적으로 유지해야 하는 프로젝트 지식이나 사용자 선호 등이 있을 수 있다.

중요한 것은 Memory가 곧바로 Context와 같은 것은 아니라는 점이다.

개념적으로는 다음과 같은 관계에 가깝다.

Memory
   ↓
검색 / Retrieval
   ↓
선택
   ↓
Context에 주입

즉,

Memory는 저장 공간이고 Context는 현재 작업 공간이다.

3. Context가 커지면 무엇이 문제인가

Context가 커진다는 것은 단순히 token 비용이 증가한다는 의미만은 아니다.

더 중요한 문제는 signal-to-noise ratio가 떨어진다는 것이다.

예를 들어 처음에는 다음 정도만 필요했다고 하자.

현재 요구사항
+
기획 판단
+
디자인 판단

그런데 코드 구현 가능성을 판단하기 위해 Claude가 수십 개의 파일을 탐색하면 다음과 같이 된다.

요구사항
+
기획 판단
+
디자인 판단
+
수십 개의 코드 파일
+
dependency 탐색 결과
+
git history
+
기존 PR
+
각종 Tool 결과

이후 구현과 테스트까지 같은 Context에서 진행하면 더 많은 정보가 쌓인다.

3.1 중요한 정보가 묻힌다

초반의 핵심 요구사항이 수많은 코드 탐색 결과 사이에 묻힐 수 있다.

요구사항
  ↓
코드 탐색
  ↓
수십 개의 파일
  ↓
git history
  ↓
추가 탐색
  ↓
구현
  ↓
테스트

workflow가 길어질수록 최초의 요구사항은 Context 안에서 상대적으로 작은 정보가 된다.

3.2 잘못된 판단이 계속 유지될 수 있다

초기 코드 탐색에서 Claude가 다음과 같이 추측했다고 하자.

이 컴포넌트가 해당 기능을 담당하는 것으로 보인다.

나중에 다른 파일을 확인하면서 이 판단이 틀렸다는 것을 발견할 수도 있다.

하지만 초기의 추측이 계속 Context에 남아 있으면 이후 판단의 전제가 될 수 있다.

초기 추측
    ↓
Context에 유지
    ↓
후속 판단
    ↓
구현
    ↓
잘못된 결과

즉 Context가 커지면 정보가 많아지는 동시에 오래된 가설도 계속 살아남는다.

3.3 모든 단계가 같은 정보를 필요로 하지 않는다

더 근본적인 문제도 있다.

릴리즈 게시 단계에서 필요한 정보는 보통 다음 정도다.

무엇이 변경되었는가
왜 변경되었는가
사용자에게 어떤 영향을 주는가

그런데 이 단계에서 구현 과정에서 읽었던 수십 개의 source file과 git history까지 기억할 필요는 없다.

따라서 중요한 것은 모든 것을 계속 기억하는 것이 아니라 다음 단계에 필요한 정보만 전달하는 것이다.

4. Skill은 “HOW TO THINK”에 가깝다

Skill을 단순히 “큰 프롬프트”라고 생각하기 쉽다.

하지만 더 중요한 역할은 특정 작업을 어떤 방식으로 수행할지 정의하는 것이다.

예를 들어 Code Review Skill이 있다면:

코드 리뷰 시 다음을 확인한다.

1. Correctness
2. Type safety
3. Accessibility
4. Performance
5. Test coverage

와 같은 판단 기준을 제공할 수 있다.

개념적으로는:

현재 Context
+
Skill
        ↓
새로운 작업 Context

이다.

즉 Skill은 기존 작업 공간에 “이런 방식으로 생각하라”는 기준을 추가한다.

5. Agent는 “WHO THINKS”에 가깝다

Agent는 단순히 Skill을 많이 넣은 것이 아니다.

핵심은 독립적인 작업 주체와 작업 공간을 만드는 것이다.

예를 들어 Main Agent가 다음을 가지고 있다고 하자.

요구사항
+
기획 판단
+
디자인 판단

여기서 Code Investigation Agent를 호출한다.

Investigation Agent는 자신의 작업 맥락에서:

파일 50개 탐색
+
dependency 분석
+
git history 탐색
+
기존 구현 확인

을 수행할 수 있다.

그리고 최종적으로 Main Agent에게 다음 정도만 전달한다.

relevant_files:
  - ...

current_behavior:
  - ...

modification_points:
  - ...

risks:
  - ...

implementation_plan:
  - ...

즉 Agent의 중요한 역할 중 하나는 큰 탐색 공간에서 작업하고 결과를 압축해서 반환하는 것이다.

6. Skill과 Agent의 본질적인 차이

결국 이렇게 정리할 수 있다.

Skill

HOW TO THINK

어떻게 생각하고 어떻게 수행할 것인지 정의한다.

Agent

WHO THINKS

누가 그 작업을 독립적으로 수행할 것인지 정의한다.

예를 들어:

Code Review Skill
→ "코드 리뷰를 할 때 이런 관점으로 검토한다."

와

Review Agent
→ "코드 리뷰라는 작업을 별도의 작업자가 수행한다."

는 다른 문제다.

그리고 둘은 함께 사용할 수도 있다.

Review Agent
      ↓
Review Skill
      +
Architecture Skill
      +
Security Skill

즉 Agent가 Skill을 활용하는 구조도 자연스럽다.

7. 그렇다면 모든 단계를 Agent로 만들면 되는가

그렇지도 않다.

Agent를 너무 많이 만들면 이번에는 Agent 사이의 handoff가 복잡해진다.

Requirement Agent
    ↓
Planning Agent
    ↓
Design Agent
    ↓
Research Agent
    ↓
Investigation Agent
    ↓
Implementation Agent
    ↓
Review Agent
    ↓
Deploy Agent

이렇게 되면 모든 단계마다 새로운 Context를 만들고 정보를 전달해야 한다.

결국 workflow가:

handoff
handoff
handoff
handoff
handoff

가 된다.

따라서 기준은 다음처럼 잡는 것이 좋다.

Skill이 적합한 경우

• 판단 기준이나 절차가 명확한 경우
• 체크리스트 기반의 일관된 판단이 필요한 경우
• 이전 단계의 Context가 크게 필요하지 않은 경우
• 작업 결과가 작고 명확한 경우

Agent가 적합한 경우

• 대량의 코드/문서/데이터 탐색이 필요한 경우
• 독립적인 분석이나 검증이 필요한 경우
• 오래 걸리는 작업인 경우
• 구현 자체를 맡겨야 하는 경우
• 결과만 상위 workflow에 전달하면 되는 경우

8. 개발 workflow를 Agent-native하게 재설계하기

이제 workflow를 개선해 다시 설계해보자.

요구사항 해석
    ↓
기획 판단
    ↓
디자인 판단
    ↓
코드 구현 가능성 판단
    ↓
코드 구현
    ↓
PR
    ↓
배포 검증
    ↓
릴리즈 게시

이것을 Skill과 Agent의 책임에 맞춰 분리하면 다음과 같다.

                    Main Agent
                         │
                         ▼
                Requirement Skill
                         │
                         ▼
                 Product Skill
                         │
                         ▼
                  Design Skill
                         │
                         ▼
              Code Investigation Agent
                         │
                     Handoff
                         │
                         ▼
               Implementation Agent
                         │
                       Diff
                         │
                         ▼
                Verification Agent
                         │
                    ┌────┴────┐
                    │         │
                   FAIL      PASS
                    │         │
                    ▼         ▼
              Implementation  PR Skill
                  Agent          │
                                 ▼
                              PR / Deploy
                                 │
                       ┌─────────┴─────────┐
                       ▼                   ▼
                  Deploy Hook       Verification Agent
                       │                   │
                       └─────────┬─────────┘
                                 ▼
                           Release Skill
                                 │
                                 ▼
                              Release

이 구조에서 Main Agent는 모든 일을 직접 수행하지 않는다.

어떤 단계로 진행할지 결정하고, 단계 사이의 결과물을 관리하는 Orchestrator에 가깝다.

9. 요구사항 해석 — Skill

요구사항 해석은 특정 업무의 방법론을 정의하는 Skill로 둔다.

Requirement Analysis Skill

Input
- 사용자 요청

Output
- 요청의 목적
- 명시적 요구사항
- 암묵적 요구사항
- 범위
- 사용자 영향
- 불확실한 부분
- 추가 확인이 필요한 질문

이 단계에서는 코드베이스를 광범위하게 탐색할 필요가 없다.

핵심은 무엇을 만들어야 하는가를 명확하게 만드는 것이다.

10. 기획 판단 — Skill

기획 판단 역시 기본적으로 Skill이다.

Product Decision Skill

1. 요구사항의 목적 확인
2. 기존 정책과 비교
3. 기존 기능으로 해결 가능한지 확인
4. 예외적인 요구인지 확인
5. 사용자 경험에 미치는 영향 확인
6. 구현해야 하는 범위 정의

다만 과거 문서나 기존 사례를 광범위하게 조사해야 한다면 Research Agent를 추가할 수 있다. 여기서 RAG를 활용할 수도 있다.

Product Decision
      ↓
Research Agent
      ↓
과거 사례 / 문서 탐색 (ex. RAG 활용)
      ↓
판단 근거 반환
      ↓
Product Decision

여기서 Skill은 판단 기준, Agent는 실제 탐색 작업을 담당한다.

11. 디자인 판단 — Skill

디자인 판단 역시 Skill로 정의할 수 있다.

Design Decision

- 기존 UI pattern으로 해결할 수 있는가?
- 새로운 component가 필요한가?
- 기존 component를 확장하는 것이 적절한가?
- interaction이 기존 UX와 일관되는가?
- responsive behavior는 어떻게 되는가?
- accessibility 요구사항은 무엇인가?
- 디자인 시스템을 위반하는 부분은 없는가?

이 단계의 결과는 다음 단계에 필요한 정보로 정리한다.

Design Decision
    ↓
UI requirements
    ↓
states
    ↓
interaction
    ↓
constraints

디자인 단계의 전체 대화를 코드 구현 Agent에게 전달할 필요는 없다.

12. 코드 구현 가능성 판단 — Agent

여기부터 Agent의 가치가 크게 증가한다.

실제 코드베이스를 탐색해야 하기 때문이다.

Code Investigation Agent의 책임은 이렇게 정의할 수 있다.

- 관련 파일 탐색
- dependency 관계 파악
- 기존 구현 확인
- API 확인
- 상태 관리 구조 확인
- 재사용 가능한 component 확인
- 수정 범위 추정
- regression 가능성 확인

중요한 것은 이 Agent가 코드를 수정하지 않도록 하는 것이다.

You are a codebase investigation agent.

Your task is to investigate the existing implementation.

Do not modify files.

Return:

1. Relevant files
2. Current behavior
3. Relevant dependencies
4. Candidate modification points
5. Risks
6. Recommended implementation approach

이렇게 하면 코드베이스를 탐색하면서 발생하는 큰 Context를 메인 workflow에서 격리할 수 있다.

13. Handoff — Context 대신 Artifact를 전달한다

여기서 가장 중요한 설계가 등장한다.

Agent가 다음 Agent에게 자신의 Context 전체를 넘겨서는 안 된다.

대신 구조화된 Artifact를 만든다.

예를 들어 코드 탐색 결과를 다음과 같이 정의할 수 있다.

task:
  summary: "..."

requirements:
  - "..."
  - "..."

relevant_files:
  - path: "src/..."
    reason: "..."

current_behavior:
  - "..."

implementation_plan:
  - "..."

constraints:
  - "..."

risks:
  - "..."

validation:
  - "..."

Investigation Agent
       │
       │ 수십 개의 파일 탐색
       ↓
     Artifact
       │
       │ 필요한 정보만 압축
       ↓
Implementation Agent

이렇게 된다.

Agent를 분리하는 것보다 더 중요한 것은 Agent 사이에 전달되는 정보의 경계를 정의하는 것이다.

14. 코드 구현 — Implementation Agent

그리고 Implementation Agent는 Investigation Agent가 남긴 Artifact를 기반으로 작업한다.

Implementation Agent

Input
- requirements
- design decision
- investigation result
- constraints

Tasks
- code modification
- test modification
- local validation

Output
- changed files
- implementation summary
- test result
- unresolved issues

이 Agent는 코드베이스 전체를 처음부터 다시 탐색할 필요가 없다.

이미 필요한 정보가 전달되었기 때문이다.

필요하다면 구현 과정에서 추가 탐색을 할 수 있지만, 탐색 자체가 목적이 되지는 않는다.

15. PR — Skill

코드 구현이 끝났다면 PR 생성은 다시 Skill의 영역으로 돌아온다. PR은 새로운 대규모 탐색보다는 이미 만들어진 결과를 정리하는 작업에 가깝기 때문이다.

Create PR Skill

1. git diff 확인
2. 변경 목적 확인
3. 테스트 결과 확인
4. 변경사항 요약
5. PR description 생성
6. reviewer에게 필요한 context 정리

16. 배포 검증 — Hook + Agent

배포 검증은 두 종류의 작업이 섞여 있다.

결정론적인 검증 예시:

HTTP status
health check
smoke test
deployment status

이런 검증은 Hook이나 일반적인 자동화가 적합하다.

반면, “이번 변경으로 실제 사용자 경험에 문제가 발생할 가능성이 있는가?” 에 대해서는 에이전트가 더 잘할 수 있다. 따라서 이런 구성이 될 수 있다.

Deploy
  │
  ├── Hook
  │    ├── health check
  │    ├── smoke test
  │    └── deployment status
  │
  └── Verification Agent
       ├── change impact
       ├── user impact
       └── regression analysis

17. Hook — 판단하지 않아도 되는 것은 시스템으로 이동한다

Hook은 workflow의 한 단계라기보다 guardrail에 가깝다.

예를 들어 파일 수정 후:

PostToolUse
    ↓
format
    ↓
lint

PR 생성 전:

PreToolUse
    ↓
typecheck
    ↓
test
    ↓
pass → continue
fail → block

배포 후:

PostDeploy
    ↓
health check
    ↓
smoke test
    ↓
monitoring check

기준은 간단하다.

LLM이 판단해야 하는 일은 Skill/Agent로 만들고, 판단할 필요 없이 반드시 실행되어야 하는 일은 Hook으로 만든다.

18. 릴리즈 게시 — Skill

릴리즈 게시 단계에서는 이미 검증된 결과를 사용자에게 전달할 수 있는 형태로 변환한다.

Release Skill

Input
- change summary
- user impact
- verification result

Output
- release title
- release summary
- user-facing changes
- known limitations

여기에서는 코드 전체 Context가 필요하지 않다. 작업은 다 완료됐으니, 릴리즈에 필요한 Artifact만 전달하면 된다.

19. 전체 구조

최종 구조를 보자.

                        ┌──────────────────┐
                        │   Main Agent     │
                        └────────┬─────────┘
                                 │
                                 ▼
                       Requirement Skill
                                 │
                                 ▼
                        Product Decision
                                 │
                                 ▼
                         Design Decision
                                 │
                                 ▼
                   ┌──────────────────────┐
                   │ Code Investigation   │
                   │ Agent                │
                   └──────────┬───────────┘
                              │
                         Artifact
                              │
                              ▼
                   ┌──────────────────────┐
                   │ Implementation       │
                   │ Agent                │
                   └──────────┬───────────┘
                              │
                            Diff
                              │
                              ▼
                   ┌──────────────────────┐
                   │ Verification         │
                   │ Agent                │
                   └──────────┬───────────┘
                              │
                    ┌─────────┴─────────┐
                    │                   │
                   FAIL                PASS
                    │                   │
                    ▼                   ▼
              Implementation          PR Skill
                  Agent                  │
                                         ▼
                                      Deploy
                                         │
                              ┌──────────┴──────────┐
                              │                     │
                         Deploy Hook        Verification Agent
                              │                     │
                              └──────────┬──────────┘
                                         ▼
                                  Release Skill
                                         │
                                         ▼
                                      Release

20. Context를 공유해야 하는 단계와 분리해야 하는 단계

따라서 모든 단계마다 Context를 새로 만드는 것은 아니다.

다음과 같이 판단하는 것이 좋다.

``` Shared Context ┌─────────────────────┐ │ 요구사항 │ │ 기획 │ │ 디자인 │ └──────────┬──────────┘ │ ▼ Isolated Context ┌─────────────────────┐ │ Code Investigation │ └──────────┬──────────┘ │ Artifact │ ▼ Isolated Context ┌─────────────────────┐ │ Implementation │ └──────────┬──────────┘ │ Diff │ ▼ Isolated Context ┌─────────────────────┐ │ Verification │ └──────────┬──────────┘ │ ▼ PR / Deploy │ ▼ Release Context

**단계마다 Context를 새로 만드는 것이 아니라, Context의 성격이 달라지는 지점에서 경계를 만든다.**

## 21. Context가 아니라 Artifact를 전달하기

지금까지를 요약해보면 제일 중요한 큰 구조는 이렇게 된다.

A의 작업 ↓ 결과를 구조화 ↓ Artifact / Handoff ↓ B의 새로운 Context

예를 들어 Investigation Agent가 30개의 파일을 읽었다고 해서 30개 파일의 탐색 과정 자체를 전달하는 것이 아니다.

InvestigationResult

• 관련 파일
• 현재 동작
• 수정 지점
• dependency
• 제약사항
• 위험요소
• 구현 제안

만 전달해, **이전 Agent의 기억을 공유하는 것이 아니라 이전 Agent의 결과를 공유하게 하는 것이 중요하다.**

# 22. 그럼 좋은 Artifact는 무엇인가

Artifact는 단순한 결과 요약이 아니다.

**다음 Agent가 자신의 Context에서 작업을 시작할 수 있도록 충분한 정보를 담은 인터페이스**다.

예를 들어 요구사항 분석 결과:

Requirement: goal: user: expected_behavior: scope: constraints: open_questions:

기획 판단 결과:

ProductDecision: decision: rationale: user_impact: accepted_scope: rejected_scope:

디자인 판단 결과:

DesignDecision: ui_change: interaction: states: responsive_behavior: accessibility: constraints:

...

등 처럼 단계별 계약을 정의할 수 있다.

# 23. Skill Chaining에서 Agent Orchestration으로

처음에는 workflow가 다음처럼 보인다.

Skill ↓ Skill ↓ Skill ↓ Skill ↓ Skill

하지만 workflow가 복잡해질수록 다음 구조처럼 책임과 역할을 확실하게 분리하고 협업하는 오케스트레이션 구조를 고려하자.

                Orchestrator
                     │
   ┌─────────────────┼─────────────────┐
   │                 │                 │
 Skill             Skill             Skill
   │                 │                 │
   └─────────────────┼─────────────────┘
                     │
                Agent 호출
                     │
          ┌──────────┼──────────┐
          │          │          │
       Agent      Agent      Agent
          │          │          │
          └──────────┼──────────┘
                     │
                  Artifact
                     │
                   Hook

Skill은 더 이상 workflow 전체를 담당하지 않는다.

**Skill은 지식을 캡슐화하고, Agent는 작업을 캡슐화한다.**

그리고 **Hook은 AI가 판단하지 않아도 되는 부분을 시스템의 영역으로 가져온다.**

## 24. 결국 좋은 AI 혹은 Agent Workflow란 무엇인가

"어떤 프롬프트를 작성해야 Claude가 일을 잘할까?" 라는 질문에서 

"어떤 작업을 어떤 Context에서 수행하게 할 것인가?"로 발전시키기.

그리고 "그 작업의 결과를 다음 작업에 어떤 Artifact 형태로 전달할 것인가?" 설계하기.

---

결국 좋은 Agent-native workflow를 설계한다는 것은 **프롬프트를 잘 쓰는 문제가 아니라 Context의 경계와 Artifact의 형태를 설계하는 것** 인 것 같다.

중요한 것은 코드 작성 자체가 아니라, **인간이 압축적으로 하던 작업단위를 가시화하고 성질을 잘 구분하는 것.** 그리고 그것을 잘 추상화, 변환하여 워프플로우로 만드는 것. 모든 것을 AI에 맡기지 않고, 필요한 방식으로 필요한 일만 시키는 것.

결국 일을 수행하는 주체가 AI나 시스템으로 옮겨가는 것일 뿐, 일을 잘 하기 위한 판단 과정과 협업의 사이에서의 정보 전달이 키라는 사실은 변하지 않는다고 생각한다.