AI를 프로젝트에 적용하는 방법 (Context Engineering)

안녕하세요 Diana 입니다.

오늘은 Claude Code를 사용하며 들던 의문을 해결해준 좋은 글을 읽게 되어 이를 기반으로 기록을 남겨보려고 합니다.

이 글은 KT Cloud 기술 블로그의 Claude Code를 선택한 이유와 개발 아키텍처 설계 실무 적용기와 Anthropic의 Effective context engineering for AI agents를 기반으로 하고 있으며, Agent · Skill · Context 구조를 알아보고 "AI를 프로젝트에 어떻게 적용하면 좋을지" 큰 그림을 잡는 것을 목표로 진행하도록 하겠습니다.

그럼 시작하겠습니다.

 

---

 

✅ 왜 AI를 써야할까?

우리는 여태껏 특정 기능을 개발하기 위해서 사용 언어를 알아야 했고, 해당 기능을 구현하는 데 쓰이는 라이브러리 등을 학습해야 했습니다.

하지만 AI가 발달함에 따라 이런 접근 방식에 변화가 생기기 시작했습니다.

Claude Code를 사용하면 CLI에 특정 기능을 입력하고 "만들어줘"라고 요청하는 것만으로 채 몇 분이 지나기도 전에 기능 하나가 완성됩니다.

우리는 이걸 프롬프트 엔지니어링이라고 부르며, 흔히 아래의 구조를 거치게 됩니다.

 

개발자 → 프롬프트를 입력한다 → AI → 결과 생성

 

물론 이는 직관적이고 확실한 방법이지만 확연한 단점을 가지고 있습니다.

 

1. 프롬프트의 규칙과 맥락이 유지되지 않는다

 

AI는 대화 기반의 인터페이스이기 때문에 프로젝트의 규칙과 맥락이 대화 밖으로 이어지지 않습니다.

"우리 프로젝트는 MVVM이야", "네트워크는 Repository 패턴을 써", "UI는 디자인 시스템 컴포넌트만 써" 같은 설명을 새 세션을 열 때마다 반복하게 되죠. 이 정보는 이미 코드베이스 안에 존재하는데도 AI에게는 매번 다시 알려줘야 합니다.

즉, 프로젝트의 규칙이 시스템이 아니라 개발자의 프롬프트(=머릿속) 에 존재하는 상태입니다.

 

2. 대화가 길어지면 AI가 규칙을 잊어버린다

 

이전 트랜스포머 글에서 알아보았듯, AI는 이전 대화 내용(토큰)을 기반으로 다음에 올 단어의 확률 분포를 계산해서 답변을 생성합니다.

그런데 대화가 길어지면 같은 질문에 다른 답을 내놓거나, 앞에서 정해둔 프로젝트 규칙을 잊어버리는 일이 매우 흔하게 발생합니다. 이를 Context Rot이라고 부릅니다.

 

왜 이런 일이 생길까요?

 

트랜스포머의 Attention에서는 모든 토큰이 서로를 참조합니다. 토큰이 n개면 n² 개의 관계가 생기는 거죠. 그래서 컨텍스트가 길어질수록 각 관계에 쏟을 수 있는 "주의력"이 얇게 퍼지게 됩니다. Anthropic은 이를 Attention Budget(주의력 예산) 이라고 표현하는데, 토큰이 하나 추가될 때마다 이 예산이 조금씩 깎여 나간다고 이해하시면 됩니다.

 

결국 하나의 프로젝트를 진행하면서 중간에 코드 스타일이 바뀐다거나 아키텍처 규칙을 위반하는 문제가 생기고, 이로 인해 사람이 진행하는 코드 리뷰의 시간과 노력이 늘어나게 됩니다.

 

3. 팀의 지식으로 쌓이지 않는다

프로젝트를 AI로 진행한다 하더라도, 비즈니스 특성상 결국 그 내용은 개발자와 팀의 지식으로 축적되어야 합니다.

하지만 각자 프롬프트를 던져 코드를 뽑아내는 방식은 팀 지식 축적에 도움이 되지 않습니다.

• 개발자 A : 자기만의 프롬프트 노하우로 작업
• 개발자 B : 완전히 다른 방식으로 작업
• 개발자 C : AI를 아예 사용하지 않음

이 상태에서는 팀의 AI 활용 방식이 "개인 경험의 합"에 불과하고, 이후 프로젝트를 복기하거나 인수인계할 때 시간을 쓰게 되는 비용 증가로 돌아올 수 있습니다.

 

✅ 그럼 AI, 어떻게 사용해야할까?

 

이런 문제를 해결하기 위해서 우리는 AI를 단순 대화 인터페이스가 아닌 시스템의 구성요소로 볼 필요가 있습니다.

기존 소프트웨어 구조는 아래의 모습을 띠고 있었습니다.

Input → Logic → Output

하지만 AI 기반의 구조에서는 이제 아래의 구조를 사용하게 되죠.

Context → Task → Result

그럼 이 Context, Task, Result는 무엇일까요?

1. Context

Context는 프로젝트의 규칙과 아키텍처를 의미합니다.

대화형 AI는 프롬프트가 주어지면 이를 토큰 단위로 분리하고, 각 토큰의 관계를 파악해 최상의 답을 찾기 위해 여러 로직을 거칩니다. 이때 Context 없이 프롬프트만으로 진행하면 AI는 일관성을 잃고 엉뚱한 답을 할 가능성이 생깁니다.

그래서 우리는 프로젝트 시작 전에 규칙, 사용 아키텍처, 컨벤션이 선언된 Context를 AI에게 제공합니다. Context가 명확하면 AI는 "추측"이 아니라 "규칙"에 따라 동작하게 됩니다.

2. Task

Task는 AI가 수행하는 작업을 의미합니다.

코드 생성, 규칙 검증, 문서 생성, 코드 분석처럼 명확히 정의된 작업 단위이며, 이 관점에서 AI는 대화 상대가 아니라 Task를 처리하는 실행 엔진이 됩니다.

3. Result

Task를 거쳐 AI가 리턴하는 결과를 의미하며, 사용자는 이 Result를 검토하고 사용하게 됩니다.

✅ Prompt Engineering vs AI Architecture

정리하면 관점이 이렇게 바뀌는 것입니다.

• Prompt Engineering : AI에게 더 좋은 질문을 던지는 방법
• AI Architecture : AI가 수행할 작업을 시스템으로 설계하는 방법

Prompt Engineering에서는 규칙이 개인의 프롬프트에 살고, 실행 단위는 한 번의 대화이며, 결과는 사람마다 세션마다 달라집니다.

AI Architecture에서는 규칙이 저장소 안의 파일에 살고, 실행 단위는 정의된 Task이며, 결과는 재현 가능하고 팀 전체가 공유할 수 있습니다.

 

Anthropic도 비슷한 관점에서 Context Engineering이라는 개념을 이야기합니다.

 

Prompt Engineering이 "좋은 프롬프트를 작성하는 방법"이라면, Context Engineering은 추론 시점에 모델의 컨텍스트 창에 들어가는 토큰 전체(시스템 프롬프트, 도구, 외부 데이터, 대화 기록 등)를 큐레이션하고 관리하는 전략입니다.

프롬프트 작성이 한 번 하고 끝나는 작업이라면, Context Engineering은 매 턴마다 "이번엔 무엇을 모델에게 보여줄 것인가"를 결정하는 반복적인 작업이라는 점이 다르죠.

 

여기서 핵심 원칙은 딱 하나입니다.

 

원하는 결과를 얻을 확률을 최대로 높이는, 가능한 한 작은 고신호(high-signal) 토큰 집합을 찾아라

앞에서 본 것처럼 컨텍스트는 무한한 자원이 아니라 쓸수록 효율이 떨어지는 유한한 자원이기 때문입니다.

 

✅ Claude Code의 구조 - Agent · Skill · Context

 

그렇다면 Claude Code는 이 구조를 어떻게 구현하고 있을까요?

Claude Code는 AI를 세 가지 요소로 나눕니다.

• Agent : 작업을 실행하는 주체
• Skill : 재사용 가능한 작업 단위
• Context : 작업할 때 지켜야 할 규칙

사람으로 비유하면 Agent는 담당자, Skill은 업무 매뉴얼, Context는 팀 컨벤션 문서라고 생각하시면 됩니다.

1. Agent - 작업을 실행하는 주체

Agent는 특정 역할을 수행하는 실행 주체입니다. 코드 리뷰 Agent, UI 분석 Agent, 문서 생성 Agent처럼 역할별로 나눌 수 있죠.

Agent는 어떤 Skill을 사용할지, 어떤 순서로 실행할지 결정하고 최종 결과를 만들어냅니다. 즉 AI Workflow의 오케스트레이터입니다.

Anthropic은 Agent를 아주 간단하게 정의합니다.

 

루프 안에서 도구를 자율적으로 사용하는 LLM

 

Claude Code에서는 .claude/agents/ 아래에 서브에이전트를 정의할 수 있는데, 여기서 중요한 점은 각 서브에이전트가 자기만의 깨끗한 컨텍스트 창을 가진다는 것입니다.

메인 Agent는 전체 계획만 잡고, 서브에이전트가 수만 토큰을 써가며 코드를 탐색하더라도 메인에게는 1,000~2,000 토큰 정도의 요약만 돌려줍니다. 앞에서 이야기한 Attention Budget을 메인이 낭비하지 않게 되는 거죠.

2. Skill - 재사용 가능한 작업 단위

Skill은 재사용 가능한 작업 단위입니다. 코드 분석, 컴포넌트 생성, 디자인 토큰 검증처럼 하나의 완결된 절차를 담고 있으며, 함수처럼 동작합니다.

Claude Code에서는 .claude/skills/<이름>/SKILL.md 형태로 작성하며, "이 작업은 이렇게 한다"는 절차와 참고 자료를 파일로 남겨둡니다.

여기서 재미있는 점은 Skill이 필요할 때만 로드된다는 것입니다. 모든 절차를 항상 컨텍스트에 올려두는 대신, 관련 작업이 들어왔을 때 해당 Skill만 읽어옵니다. 이것도 Attention Budget을 아끼는 방법 중 하나입니다.

3. Context - 작업 규칙

Context는 AI가 작업을 수행할 때 필요한 규칙입니다. 코드 컨벤션, 디자인 시스템 규칙, 아키텍처 가이드, 절대 하면 안 되는 것 등이 여기에 해당합니다.

Claude Code에서는 프로젝트 루트의 CLAUDE.md가 이 역할을 합니다. 이 파일은 세션이 시작될 때 항상 컨텍스트에 포함되기 때문에, 팀의 규칙을 여기에 적어두면 "매번 설명하는" 문제가 사라집니다.

그럼 Context는 어떻게 써야 잘 쓰는 걸까요? Anthropic의 글에서 기준 몇 가지를 정리해보았습니다.

 

적절한 높이(Right Altitude)를 지켜라

 

한쪽 극단은 if-else처럼 모든 경우를 하드코딩한 프롬프트입니다. 깨지기 쉽고 유지보수가 어렵습니다.

반대쪽 극단은 "잘 짜줘"처럼 너무 추상적이라 아무 신호도 주지 못하는 프롬프트입니다.

좋은 Context는 그 중간, 행동을 충분히 안내하면서도 모델이 판단할 여지를 남기는 수준에 있습니다.

 

최소한의, 그러나 충분한 정보

 

"최소"가 "짧게"를 뜻하지는 않습니다. 기대하는 행동을 온전히 설명할 수 있는 최소 집합이면 됩니다.

Anthropic이 권하는 순서는 이렇습니다.

1. 최소한의 프롬프트로 먼저 돌려본다
2. 실패하는 지점을 찾는다
3. 그 부분에 대한 지시와 예시를 추가한다

예시는 엣지 케이스 나열이 아니라 대표 사례로

가능한 모든 예외를 프롬프트에 욱여넣는 대신, 기대하는 행동을 잘 보여주는 다양하고 전형적인 예시 몇 개를 고르는 편이 효과적입니다. LLM에게 예시는 "천 마디 말보다 나은 그림"입니다.

✅ Context는 언제 로드되는가 - Just in Time

"그럼 필요한 정보를 처음부터 전부 넣어주면 되지 않을까?"라는 생각이 들 수 있습니다.

하지만 위에서 본 것처럼 컨텍스트는 유한한 자원입니다.

 

그래서 Anthropic은 필요한 데이터를 전부 사전에 로드하는 대신, 파일 경로 · 쿼리 · 링크 같은 가벼운 식별자만 들고 있다가 필요할 때 도구로 불러오는 방식을 소개합니다. 이를 Just in Time 컨텍스트라고 부릅니다.

 

사람도 모든 정보를 외우지 않고 파일 시스템, 북마크, 받은편지함 같은 외부 인덱스를 두고 필요할 때 꺼내 보죠. AI도 마찬가지입니다.

tests/ 폴더 안의 test_utils.py와 src/core/ 안의 test_utils.py는 파일명이 같아도 다른 의미를 갖습니다. 폴더 구조, 네이밍, 타임스탬프 자체가 AI에게 힌트가 되는 거죠.

 

Claude Code는 두 방식을 섞어 씁니다.

• CLAUDE.md : 세션 시작 시 무조건 컨텍스트에 포함 (사전 로드)
• glob, grep, 파일 읽기 : 작업 중 필요한 파일만 그때그때 탐색 (Just-in-Time)

✅ 긴 작업에서 맥락을 유지하는 방법

대규모 리팩토링처럼 작업이 컨텍스트 창의 크기를 넘어가는 경우도 있습니다. 컨텍스트 창이 커지기를 기다리는 것만으로는 해결되지 않는데, 창이 아무리 커도 오염과 관련성 문제는 남기 때문입니다.

Anthropic이 소개하는 세 가지 접근은 다음과 같습니다.

1. Compaction(압축)

컨텍스트가 한계에 가까워지면 지금까지의 대화를 요약하고, 그 요약으로 새 컨텍스트 창을 시작하는 방식입니다. Claude Code의 /compact가 이 역할을 하죠.

아키텍처 결정, 아직 해결 안 된 버그, 구현 세부 사항은 남기고, 중복된 도구 출력 같은 것은 버립니다. 한참 전에 읽은 파일 원문을 다시 볼 필요는 없으니까요.

2. Structured Note-taking(구조화된 메모)

Agent가 작업 중간중간 컨텍스트 창 밖의 파일(예: NOTES.md, TODO 리스트)에 진행 상황을 기록하고, 나중에 다시 읽어오는 방식입니다.

Anthropic은 Claude가 포켓몬 게임을 플레이하며 수천 스텝에 걸쳐 "지금까지 어디서 몇 스텝을 훈련했고 레벨이 몇 올랐는지"를 메모로 관리한 사례를 소개합니다. 컨텍스트가 리셋되어도 자기 메모를 읽고 몇 시간짜리 작업을 이어갈 수 있었죠.

3. Sub-agent Architecture(서브에이전트)

앞에서 본 것처럼 하나의 Agent가 전체 상태를 다 들고 가는 대신, 전문화된 서브에이전트가 각자 깨끗한 컨텍스트에서 세부 작업을 하고 요약만 메인 Agent에게 돌려주는 구조입니다.

• Compaction : 대화를 계속 주고받아야 하는 작업에 적합
• Note-taking : 마일스톤이 명확한 반복적 개발에 적합
• Sub-agent : 병렬 탐색이 이득인 복잡한 리서치 · 분석에 적합

✅ 지속 실행 구조 - Loop

Agent, Skill, Context가 정의되면 자연스럽게 다음 질문이 나옵니다.

 

이 작업을 사람이 매번 시키지 않고 계속 돌릴 수는 없을까?

 

KT Cloud 글에서는 이를 Loop라는 개념으로 설명합니다.

기존 방식이 Prompt → Result 였다면, Loop 구조에서는 Scheduler → Agent → Skill → Result 가 됩니다.

스케줄러(cron, CI 파이프라인, PR 이벤트 등)가 일정 간격 또는 특정 이벤트마다 Agent를 실행하고, Agent는 정의된 Skill로 작업을 수행한 뒤 결과를 남깁니다.

이렇게 되면 AI는 "질문하면 답하는 도구"에서 개발 프로세스 안에서 지속적으로 동작하는 구성 요소로 바뀝니다. PR이 올라올 때마다 리뷰 Agent가 돌거나, 매일 아침 컨벤션 위반을 점검하는 식이죠.

✅ 정리

오늘 알아본 내용을 정리하면 다음과 같습니다.

1. 프롬프트만으로 AI를 쓰면 맥락 유실, 비일관성, 지식 파편화 문제가 생긴다
2. 원인은 AI의 성능이 아니라 AI를 사용하는 구조에 있다
3. AI를 시스템 구성요소로 보면 구조는 Context → Task → Result 가 된다
4. Claude Code는 이를 Agent(실행 주체) · Skill(작업 단위) · Context(규칙) 로 구현한다
5. 컨텍스트는 유한한 자원이므로, 필요한 것만 필요할 때 넣는 것이 핵심이다(Context Engineering)
6. 긴 작업은 Compaction · Note-taking · Sub-agent 로 맥락을 유지한다
7. Loop 를 붙이면 AI는 개발 프로세스 안에서 스스로 돌아가는 구성요소가 된다

KT 개발 블로그를 확인해보니 AI 관련 글이 잘 정리되어 있던데 이후 추가로 학습하며 추가해보도록 하겠습니다.

감사합니다.

 

출처

https://tech.ktcloud.com/entry/2026-04-ktcloud-claude-ai-architecture-%EC%8B%A4%EB%AC%B4-%EC%A0%81%EC%9A%A9?category=739828

https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents