Context, Memory, Skills와 Agents 이해하기

오늘날 Coding Agent를 사용하다 보면 몇 분 안에 여러 용어를 만나게 됩니다. Context, Memory, Agent Files, Skills, Tools, 그리고 Agents 자체입니다. 여기에 AGENTS.md, CLAUDE.md, Custom Instructions, SKILL.md처럼 제품마다 다른 이름도 추가됩니다.

처음 보면 이 단어들이 모두 비슷한 것을 가리키는 것처럼 느껴집니다.

모델이 어떤 방식으로든 알고 있는 정보.

처음 써 볼 때는 이 정도 이해로도 충분할 수 있습니다. 하지만 왜 Agent가 어떤 정보는 반영하고, 어떤 정보는 더 이상 사용할 수 없는지, 왜 규칙을 매번 똑같이 따르지 않는지, 또는 왜 특정 작업에서 갑자기 특정 Workflow를 사용하는지 이해하려면 이 설명은 너무 거칠어집니다.

더 중요한 질문은 이것입니다.

Coding Agent는 무엇을 알아야 하고 어떻게 일해야 하는지를 어디에서 얻을까요?

이 문제는 간단한 비유로 꽤 멀리 설명할 수 있습니다. 인공적인 사람을 떠올리기보다 책상이 있는 작업 환경을 생각해 봅시다. Model은 이미 어느 정도의 지식과 능력을 가지고 있습니다. 책상 위에는 현재 작업에 사용할 수 있는 정보가 놓입니다. 옆에는 자료를 보관하는 Archive가 있고, 이 작업 환경에서 지켜야 할 규칙이 있고, 특정 작업을 위한 Playbook이 있으며, 실제 행동을 가능하게 하는 Tools가 있습니다.

단순화하면 다음과 같습니다.

Model
=
이미 가지고 있는 지식과 능력

Context
=
지금 책상 위에 놓여 있는 것

Memory
=
정보를 보관해 두었다가
나중에 다시 책상 위로 가져올 수 있는
Archive 또는 Notebook

Agent Files
=
이 작업 환경의 규칙

Skills
=
특정 종류의 작업을 위한
Playbook 또는 작업 지침

Tools
=
시스템이 행동할 때 사용하는 도구

Agent
=
하나의 Task를 수행하면서
이 메커니즘들을 함께 사용하는 시스템

이 비유는 시스템 안에서 각 요소가 맡는 역할을 설명합니다. LLM이 인간의 뇌처럼 작동한다거나 Agent가 인간과 같은 기억을 가진 디지털 직원이라는 뜻은 아닙니다.

이 구분은 중요합니다. 기술적 메커니즘을 인간의 인지와 너무 직접적으로 대응시키는 순간 많은 오해가 생기기 때문입니다.

Context는 왜 단기기억이 아닌가

Context는 종종 LLM의 단기기억이나 작업기억으로 설명됩니다. 아주 거친 일상적 비유로는 이해할 수 있습니다. 정보가 한정된 처리 범위 안에서 사용되고 다음 동작에 영향을 주기 때문입니다.

하지만 기술적으로는 이 비유가 금방 잘못된 방향으로 이어집니다. 인간의 작업기억은 동적인 생물학적 상태입니다. 내용을 계속 유지해야 하고, 시간이 지나면 희미해질 수 있으며, 다양한 인지 과정의 영향을 받습니다.

LLM의 Context는 다릅니다. 특정 Model Invocation에 명시적으로 제공된 정보입니다. 어떤 정보가 현재 Context 안에 포함되어 있는 동안에는 Model이 원칙적으로 그것을 고려할 수 있습니다. 그렇다고 Context 안의 모든 정보를 똑같이 안정적으로 찾고, 같은 비중으로 다루고, 실제 답변에 활용한다는 뜻은 아닙니다.

그래서 책상이라는 비유가 더 적합합니다. 문서가 책상 위에 놓여 있어도 사람이 그 안의 결정적인 한 줄을 놓칠 수 있습니다. 책상이 아주 크더라도 자료가 너무 많이 쌓여 있으면 중요한 정보가 덜 눈에 띌 수 있습니다.

책상 위에 올릴 수 있다는 것과 그 내용을 안정적으로 활용한다는 것은 서로 다른 능력입니다.

Model이 이미 가지고 있는 것

책상 위에 어떤 자료를 놓기 전에도 Model은 이미 존재합니다. Model Weights는 Training과 Post-Training을 통해 형성되었고, Model이 이미 무엇을 할 수 있는지, 어떤 Pattern을 배웠는지를 크게 결정합니다.

우리의 작업 환경 비유에서는 이것을 교육, 경험, 이미 내재화된 지식 정도로 생각할 수 있습니다. 물론 이것도 역할을 설명하기 위한 비유일 뿐입니다. Model이 인간처럼 교육을 기억하거나 실제 직업 경험을 갖는 것은 아닙니다.

기술적으로 더 중요한 구분이 있습니다. Context에 추가 정보를 넣거나 Memory System을 사용해도 일반적으로 Model Weights는 바뀌지 않습니다. Model이 새로 Training되는 것이 아닙니다.

예를 들어 Coding Agent가 특정 Repository에서는 npm이 아니라 pnpm을 사용한다는 사실을 기억한다고 해도 Base Model이 이 사실을 영구적으로 새로 학습한 것은 아닙니다. 주변 시스템이 정보를 저장하고 필요할 때 다시 제공하는 것입니다.

Context – 지금 책상 위에 무엇이 있는가

Context는 단순화하면 현재 처리 단계에서 Model이 사용할 수 있는 정보입니다.

여기에는 당연히 현재 사용자의 요청이 들어갈 수 있습니다. 하지만 실제 Agent System에서는 사용자의 요청이 전체 Context의 작은 일부에 불과한 경우가 많습니다. System Instructions, Conversation History, Repository Files, Search Results, Tool Descriptions, Test Results, Compiler Errors, API Responses, 불러온 Agent Files, 활성화된 Skills, 조회된 Memories가 모두 현재 Context에 들어갈 수 있습니다.

실패한 Test를 조사하는 Coding Agent라면 다음과 같은 정보를 동시에 사용할 수 있습니다.

작업 설명
+
관련 Repository Files
+
Architecture Rules
+
Test Code
+
직전 실패한 Test의 Output
+
이전 변경 사항
+
현재 작업 지시

Model은 Training 중에 이런 내용을 미리 본 적이 없어도 됩니다. 새로운 Library의 Documentation이나 내부 Repository의 일부를 제공하면 현재 처리 과정에서 그 내용을 활용할 수 있습니다.

그래서 다음과 같은 간단한 표현이 꽤 유용합니다.

Context는 지금 책상 위에 놓여 있는 것입니다.

Agent Interface가 복잡하게 보여도 원리는 생각보다 단순합니다. Agent가 File 하나를 열었다고 해서 그것이 자동으로 Model Weights의 새로운 지식이 되는 것은 아닙니다. Search Result도 마찬가지입니다. 우선은 다음 Model Invocation에서 사용할 수 있는 정보가 하나 더 생긴 것입니다.

Context Window – 책상은 얼마나 큰가?

이 시리즈의 두 번째 글에서 Context Window를 기술적인 용량 제한으로 이미 다뤘습니다. 단순화하면 하나의 Model Invocation에서 얼마나 많은 Material을 함께 고려할 수 있는지를 뜻합니다. Token Budget이 입력, 내부 System Context, 출력에 어떻게 나뉘는지는 Model과 Product에 따라 다릅니다.

우리의 비유에서는 책상의 크기입니다.

큰 책상은 분명 유용합니다. 정보를 제거하거나 요약하거나 다시 불러오기 전에 Agent가 더 많은 Code, Conversation History, Documentation을 동시에 유지할 수 있습니다.

하지만 크기만으로 작업 환경의 품질을 판단할 수는 없습니다. 만 장의 문서가 아무렇게나 쌓인 큰 책상에는 필요한 정보가 전부 들어 있을 수도 있습니다. 반대로 더 작은 책상에 관련 API Documentation, 영향받는 Modules, Architecture Rules, 현재 Test Failure만 정확히 놓여 있다면 실제 작업에는 훨씬 더 유용할 수 있습니다.

실제 Agent System을 이해할 때는 몇 가지 질문을 나누어 보는 것이 좋습니다. 기술적으로 얼마나 많은 Context를 넣을 수 있는가? 그중 실제로 관련 있는 정보는 무엇인가? 어떤 정보가 실제로 선택되고 언제 제공되는가? 마지막으로 Model은 선택된 정보를 얼마나 안정적으로 활용하는가?

큰 Context Window는 주로 첫 번째 질문에만 답합니다.

Context Engineering – 무엇을 책상 위에 올릴 것인가

여기서 다시 Context Engineering이라는 개념으로 이어집니다.

Context Engineering은 가능한 많은 자료를 가능한 큰 Prompt에 넣는다는 뜻이 아닙니다. 큰 Codebase에서는 오히려 관련 정보를 골라내고, 적절히 구조화하고, 필요한 시점에 제공하는 일이 중요합니다. Anthropic은 이를 위해 전통적인 Retrieval과 “just in time” 방식을 결합하는 접근을 설명합니다. 추가 정보는 작업 도중에야 Files, Search, Tools를 통해 불러옵니다. [8]

구체적인 변경 작업이라면 영향받는 Modules, 현재 Tests, API Contract, 몇 가지 Architecture Rules, 실패한 Build Output 정도가 유용한 Context일 수 있습니다. 전체 Monorepo, 지난 5년간의 모든 ADR, 모든 Coding Convention을 넣으면 정보량은 늘어나지만 Context가 자동으로 더 좋아지는 것은 아닙니다.

Context Engineering은 무엇이 책상 위에 올라갈지를 결정합니다.

이 과정을 체계적으로 설계하는 방법은 별도의 주제입니다. 여기서는 Context가 고정된 지식 저장소가 아니라는 점만 기억하면 충분합니다. Agent System은 작업하면서 Context를 계속 구성합니다.

Memory – 작업 공간 옆의 Archive

이제 Memory를 더 정확히 구분할 수 있습니다.

Agent System이 하나의 작업 단계나 Session을 넘어 정보를 유지해야 한다면 그 정보는 어딘가에 저장되어야 합니다. File, Database, Search Index 또는 다른 Persistence Mechanism일 수 있습니다. 이후 시스템이 관련 정보를 다시 찾아 현재 작업에 제공할 수 있습니다.

단순화하면 다음과 같습니다.

Memory
↓
Retrieval
↓
Context
↓
Model

따라서 Memory는 Model의 인간식 장기기억이라기보다 책상 옆의 Archive나 Notebook에 더 가깝습니다.

예를 들어 사용자가 선호하는 출력 방식, 팀이 이전에 거부했던 기술 선택, 특이한 Build Step, 장기 작업이 마지막으로 중단된 위치 등이 저장될 수 있습니다.

중요한 것은 흐름입니다. 정보가 Archive에 저장되어 있기만 하면 Model이 자동으로 그것을 사용하는 것은 아닙니다. Agent System이 정보를 찾아 적절한 형태로 다시 책상 위에 올려야 합니다.

Context는 현재 사용할 수 있는 작업 자료입니다. Memory는 저장되었다가 나중에 다시 Context가 될 수 있는 정보입니다.

다만 Product Terminology는 완전히 통일되어 있지 않습니다. 예를 들어 Claude Code는 CLAUDE.md Files와 Auto Memory를 두 개의 상호보완적 Memory System으로 명시적으로 설명합니다. 동시에 Anthropic은 두 종류 모두 결국 Context로 사용된다고 설명합니다. CLAUDE.md에는 사람이 관리하는 Persistent Instructions가 들어가고, Auto Memory에는 Agent가 직접 기록한 Learnings와 Patterns가 들어갑니다. [3]

그래서 우리의 Mental Model에서는 역할을 기준으로 나누는 편이 더 유용합니다. 사람이 관리하는 Repository 및 Project Rules는 Agent Files로 보고, 여기서 Memory는 여러 단계나 Session을 넘어 저장되었다가 나중에 다시 사용할 수 있는 정보라고 하겠습니다.

이 구분은 이해를 돕기 위한 범주이지 Vendor가 반드시 따라야 하는 법칙이 아닙니다. 기술적으로 중요한 경계는 그대로입니다. 이런 정보를 저장한다고 해서 일반적으로 Model Weights가 변경되지는 않습니다. 이는 Persistence와 재사용이지 자동 Training이 아닙니다.

Agent Files – 이 프로젝트에서는 어떻게 일하는가

Agent Files에 오면 용어는 더 Product-specific해집니다.

AGENTS.md는 Coding Agents를 위한 Instructions의 Open Format으로 자리 잡고 있습니다. 대략 “Agent를 위한 README”라고 볼 수 있습니다. Build Commands, Tests, Conventions, Project-specific Context를 넣는 예측 가능한 위치를 제공합니다. 현재 여러 Coding Agent Tools가 이 형식을 지원하고 있습니다. [1]

GitHub Copilot은 .github/copilot-instructions.md와 Path-specific NAME.instructions.md를 통한 자체 Repository Instructions를 지원합니다. Agent 환경에서는 중첩된 AGENTS.md도 지원하고, Repository Root에서는 CLAUDE.md나 GEMINI.md도 사용할 수 있습니다. [2]

Claude Code는 기본적으로 CLAUDE.md와 .claude/rules/를 사용합니다. AGENTS.md를 Native Format으로 자동 해석하지는 않지만, 여러 Agent System에서 동일한 규칙을 공유하고 싶다면 CLAUDE.md에서 기존 AGENTS.md를 Import하라고 현재 Documentation에서 명시적으로 안내합니다. [3]

따라서 “Agent File”을 하나의 특정 Standard 이름처럼 다루는 것은 적절하지 않습니다. 이 글에서는 Coding Agent에게 Project-specific Rules와 Working Context를 제공하는 Files의 상위 개념으로 사용합니다.

핵심 질문은 다음과 같습니다.

이 프로젝트에서는 어떻게 일하는가?

이런 File에는 Architecture Rules, Naming Conventions, Dependency Boundaries, Test Strategies, Build Commands, 기타 Project-specific Decisions가 들어갈 수 있습니다.

Angular Project라면 예를 들어 다음과 같을 수 있습니다.

# Frontend Architecture

- Components는 Business Logic을 Orchestrate하지 않는다.
- Domain State는 `domain/+state` 아래에 둔다.
- HTTP Access는 `infrastructure`에 둔다.
- Local State에는 Signals를 사용한다.
- 새로운 Features에는 Unit Tests가 필요하다.

이 규칙들은 아직 Feature를 구현하는 구체적인 Workflow를 설명하지 않습니다. 대신 이 Repository 안에서 어떤 Boundaries를 지켜야 하는지 알려 줍니다.

다른 프로젝트는 충분히 정당하게 NgRx를 사용할 수 있고, HTTP Access를 다르게 배치할 수 있으며, 다른 Test Boundaries를 정의할 수도 있습니다. 그렇기 때문에 좋은 Agent File은 “소프트웨어 개발은 언제나 이렇게 해야 한다”는 일반론의 모음이 아닙니다.

좋은 작업이 이곳에서 어떤 모습인지 설명하는 것입니다.

Agent Files는 Universal Best-Practice Package가 아니다

여기서부터는 단순한 용어 설명을 조금 넘어갑니다.

잘 운영되는 프로젝트의 대형 AGENTS.md, CLAUDE.md, 또는 Copilot Instructions 모음을 그대로 가져오고 싶은 유혹은 큽니다. 이미 누군가 많은 노력을 들였고, 대부분의 규칙도 처음 보면 합리적으로 들리기 때문입니다.

문제는 좋은 아이디어를 참고하는 데 있지 않습니다. Project-specific Decisions를 Universal Best Practices로 착각할 때 문제가 생깁니다.

어떤 Repository는 의도적으로 Feature Slices를 사용하고, 다른 Repository는 Technical Layer 중심으로 구성될 수 있습니다. 한 팀은 Signals를 주요 State Model로 사용하고, 다른 팀은 NgRx를 사용할 수 있습니다. 한 프로젝트에서는 Integration Tests가 가장 중요한 Safety Boundary일 수 있고, 다른 곳에서는 Unit Tests가 훨씬 큰 역할을 할 수 있습니다. 같은 Framework를 사용한다고 해서 Architecture Rules까지 자동으로 같아지는 것은 아닙니다.

다른 프로젝트의 규칙을 매우 정밀하게 Agent에게 입력한다고 해서 결과가 자동으로 좋아지지는 않습니다. 오히려 잘못된 규칙을 매우 일관되게 적용하는 결과가 나올 수도 있습니다.

Agent Files는 Universal Best-Practice Package가 아닙니다. 실제 프로젝트의 Architecture와 Working Style을 설명해야 합니다.

Skills – 이런 종류의 작업은 어떻게 수행하는가

Skill은 다른 질문에 답합니다.

Agent File이 특정 환경에서 어떻게 일해야 하는지를 설명한다면, Skill은 특정 종류의 작업을 수행하는 Playbook을 설명합니다.

이런 종류의 작업은 어떻게 수행하는가?

Code Review, Systematic Debugging, TDD, Migration, Architecture Review, 반복되는 Feature Structure 구현 등이 될 수 있습니다.

우리의 작업 환경 비유에서 Skill은 House Rules가 아니라 Playbook입니다.

현재 Open Specification으로 제공되는 Agent Skills Format은 이 메커니즘을 이해하기 쉽게 보여 줍니다. Skill은 최소한 하나의 SKILL.md를 포함하는 Directory로 구성됩니다. 이 파일에는 name, description 같은 Metadata와 실제 Instructions가 들어갑니다. Skill에는 Scripts, Reference Material, 기타 Assets도 포함될 수 있습니다. 이 형식은 원래 Anthropic이 개발했고 2025년 말 Open Standard로 공개되었습니다. [4]

Skill은 예를 들어 다음과 같이 정의될 수 있습니다.

Code Review

1. Baseline 대비 Diff를 확인한다.
2. Functional Requirement를 점검한다.
3. Project Rules를 적용한다.
4. Architecture Violations를 찾는다.
5. Tests와 Verification을 점검한다.
6. Findings를 중요도에 따라 구조화한다.

이는 “HTTP Access는 infrastructure에 둔다” 같은 Project Rule과는 다릅니다. Skill은 Workflow를 설명하고, Agent File은 그 Workflow 안에서 적용해야 하는 Rules를 제공합니다.

Skill은 자동으로 “배운 능력”을 뜻하지 않는다

Skill이라는 단어 자체는 약간 오해를 부를 수 있습니다.

사람에게 Skill은 보통 내재화된 능력으로 이해됩니다. 자전거 타기, Touch Typing, 익숙해진 Debugging Method는 매번 작업 전에 읽는 Markdown File에 저장되어 있지 않습니다.

Agent Skills에서는 다른 그림이 실제 메커니즘에 더 가깝습니다. Workflow가 File 또는 Structured Resource로 저장됩니다. 해당 Skill이 관련 있다고 판단되면 Agent System이 Instructions를 불러오고, Model에 Additional Context로 제공합니다.

SKILL.md
↓
load
↓
Context
↓
Model

이름은 Skill이지만, 기술적으로는 종종 내재화된 능력보다 Playbook에 더 가깝습니다.

물론 Model 자체는 Training을 통해 이미 많은 능력을 가지고 있습니다. 특정 Behavior가 Training이나 Fine-Tuning을 통해 Model Weights에 내재화되어 있다면 인간의 숙련된 Skill에 대한 비유가 더 가까워집니다.

반면 TDD Workflow를 설명하는 SKILL.md는 Model Weights를 바꾸지 않습니다. Agent System이 재사용할 수 있는 Playbook을 제공할 뿐입니다.

Agent File과 Skill은 서로 보완한다

구체적인 Coding Task를 보면 차이가 더 분명해집니다.

다음과 같은 지시가 있다고 합시다.

Update Slice를 구현하라.

Agent File은 Domain State가 domain/+state에 있어야 하고, Components가 Business Orchestration을 하지 않으며, HTTP Access는 Infrastructure를 거쳐야 하고, 새로운 변경에는 Unit Tests가 필요하다고 정의할 수 있습니다.

반면 Project-specific Skill은 실제 작업 절차를 정의할 수 있습니다.

Update Slice 구현

1. Command를 확인하거나 생성한다.
2. 기존 Read State를 분석한다.
3. Application Use Case를 구현한다.
4. Infrastructure를 연결한다.
5. Invalidation을 고려한다.
6. Tests를 추가한다.
7. Verification을 수행한다.

두 메커니즘은 경쟁하지 않습니다. Skill은 이 종류의 작업에서 어떤 Steps가 필요한지 설명합니다. Agent File은 그 Steps를 수행할 때 이 Project에서 어떤 Rules를 지켜야 하는지 설명합니다.

짧게 표현하면:

Agent File
=
여기서는 어떻게 일하는가?

Skill
=
이런 종류의 작업은 어떻게 수행하는가?

작업 환경 비유를 계속 쓰면:

Agent File
=
House Rules

Skill
=
Playbook

제품마다 이 경계를 기술적으로 정확히 같은 방식으로 구현하는 것은 아닙니다. 그래도 Mental Model로는 유용합니다. 서로 다른 두 가지 Responsibility를 눈에 보이게 해 주기 때문입니다.

Progressive Disclosure – 필요한 Playbook만 책상 위에 올리기

Skills가 많아지면 바로 Context 문제가 생깁니다. 단순한 Bugfix 하나를 처리하는데 Release Management, Data Migration, UX Review, Incident Response, 여러 Feature Type의 전체 작업 지침까지 한꺼번에 필요하지는 않습니다.

그래서 Open Agent Skills Specification은 Progressive Disclosure를 핵심 Design Principle로 둡니다. 호환 Client는 처음에는 Skill의 Name과 Description만 노출할 수 있습니다. Skill이 활성화되면 전체 SKILL.md가 Context에 들어가고, 추가 Scripts, References, Assets는 필요한 시점에만 사용될 수 있습니다. Discovery와 Activation을 어떻게 구현할지는 개별 Agent System의 책임입니다. [4]

우리의 비유에서는 방 한쪽에 Playbook이 꽂힌 선반이 있는 셈입니다. 모든 Playbook이 항상 펼쳐진 채 책상 위에 놓여 있지는 않습니다. 관련 Task가 생기면 필요한 Playbook만 꺼냅니다.

이렇게 하면 Context를 절약하고 불필요한 Instructions를 줄일 수 있습니다. 동시에 Skill이 Model이 영구적으로 “알고 있는 것”과는 다르다는 점도 다시 드러납니다. Agent System이 어떤 정보가 언제 Working Area로 들어올지를 관리합니다.

재사용 가능하다는 것이 Universal이라는 뜻은 아니다

Skills는 Agent Files보다 재사용하기 쉬운 경우가 많습니다. Systematic Debugging, Code Review, TDD Workflow처럼 잘 정리된 절차는 여러 프로젝트에서 유용할 수 있습니다.

하지만 그렇다고 자동으로 모든 Project에서 동일하게 쓸 수 있는 것은 아닙니다.

Skill이 실제 Architecture나 Team Development Process에 가까워질수록 더 Project-specific해집니다. 예를 들어 create-angular-crud-slice Skill은 이 Project가 Slice를 어떻게 정의하는지 알아야 합니다. add-domain-command Skill은 해당 Codebase에서 Commands, State, Application Layer가 어떻게 구성되어 있는지에 의존합니다. Legacy Migration Skill은 오히려 Greenfield Project에서는 절대 복제하면 안 되는 구조를 의도적으로 다뤄야 할 수도 있습니다.

Skill이 Architecture, Domain Rules, 실제 Development Process에 가까워질수록 Project에 맞춘 조정이 더 많이 필요합니다.

따라서 “Agent Files는 Local이고 Skills는 Global이다”라는 구분은 맞지 않습니다. 둘은 역할이 다릅니다. Agent Files는 본질적으로 환경과 강하게 연결되는 경우가 많고, Skills는 반복 가능한 작업을 설명하지만 범위는 매우 일반적인 것부터 매우 Project-specific한 것까지 넓을 수 있습니다.

여기서부터 Engineering이 시작된다

Context와 Memory는 처음에는 비교적 중립적인 기술 메커니즘으로 설명할 수 있습니다. 정보가 제공되고, 저장되고, 나중에 다시 사용할 수 있게 됩니다.

하지만 Agent Files와 Skills에서는 Team이 결정을 내려야 합니다. 실제로 의도한 Architecture는 무엇인가? 새로운 변경이 어떤 Patterns를 따라야 하고, 어떤 Patterns는 단지 과거의 흔적일 뿐인가? 어떤 Commands가 정상 Workflow에 포함되는가? 어떤 변경에 어떤 Tests가 필요한가? 이 Repository에서 “done”은 무엇을 의미하는가?

Skills에서는 더 많은 질문이 생깁니다. 이 Team에서 좋은 Code Review는 무엇인가? 어떤 Debugging Steps가 실제로 도움이 되었는가? Feature는 어떻게 Slice해야 하는가? 어떤 Verification은 절대 생략하면 안 되는가?

자신들의 Working Style을 설명하기 어려운 Team은 그것을 좋은 Agent Files와 Skills로 옮기는 데에도 어려움을 겪습니다.

여기서부터 일종의 Engineering이 시작됩니다. 그렇다고 처음부터 완벽한 Agent System을 설계해야 한다는 뜻은 아닙니다. 더 현실적인 방식은 반복적입니다. 실제 Tasks를 관찰하고, 반복되는 실패를 찾고, Rules를 명시적으로 만들고, Skill의 범위를 좁히고, Agent Behavior를 확인한 뒤 Instructions를 개선합니다.

Anthropic도 Skills를 설계할 때 구체적으로 관찰되는 Agent Behavior의 빈틈과 대표적인 Tasks에서 시작하고, 실제 시나리오에서 동작을 관찰하면서 계속 개선할 것을 권장합니다. [4]

Markdown File이 그럴듯해 보인다고 해서 좋은 Skill이 되는 것은 아닙니다.

좋은 Skill은 실제 Task에서 Agent Behavior를 안정적으로 개선해야 합니다.

이 원칙은 새로운 형태의 Cargo Cult를 피하게 해 줍니다. 방대한 Agent Configurations를 모아 놓고 실제 효과는 한 번도 검증하지 않는 상황 말입니다.

Matt Pocock의 “Skills for Real Engineers” – 정답이 아니라 Inspiration

이런 Playbook을 어떻게 구성할 수 있는지 보여 주는 현재의 좋은 예 중 하나가 Matt Pocock의 Skills for Real Engineers Repository입니다. code-review, diagnosing-bugs, tdd, implement, Research 등 여러 Engineering Skills를 제공합니다. 예를 들어 implement Workflow는 이미 내려진 Decisions를 전제로 하고, 정해진 Seams에서 TDD를 사용하며, 마지막에 Code Review를 수행합니다. Debugging Skill은 Reproduction, Minimization, Hypothesis, Instrumentation, Fix, Regression Test로 이어지는 비교적 엄격한 진단 사이클을 정의합니다. [5]

중요한 것은 이 Files를 모든 Repository에 그대로 복사하는 것이 아닙니다. 더 흥미로운 부분은 구조입니다. Tasks가 비교적 좁게 나뉘고, Working Style에 이름이 붙고, 큰 Workflow가 작은 Skills를 조합할 수 있으며, 반복되는 Engineering Practices가 명시적으로 표현됩니다.

그래서 이 Repository는 자신의 Skills를 설계할 때 Scope와 Structure를 참고하는 Inspiration으로 특히 유용합니다. 어떤 종류의 Working Knowledge를 Playbook으로 표현할 수 있는지 보여 주고, Skills가 단순한 Prompt Trick이 아니라 완전한 Feedback Loop를 나타낼 수도 있다는 점을 보여 줍니다.

하지만 Project-specific Decisions까지 대신 내려 주는 것은 아닙니다. 어떤 Review가 좋은 Review인지, 어떤 Test Boundaries가 중요한지, 어떤 Architecture를 보존해야 하는지, 어떤 Workflow가 특정 Codebase에 맞는지는 여전히 각 Project에서 결정해야 합니다.

구조는 참고할 수 있지만, 내용은 결국 스스로 만들어 가야 합니다.

Tools – Agent는 무엇으로 행동하는가

지금까지는 주로 Model에게 어떤 정보와 Instructions가 제공되는지를 다뤘습니다.

Tools는 다른 차원을 바꿉니다. 시스템이 환경에서 정보를 가져오거나 실제로 환경에 Actions를 수행할 수 있게 합니다.

Tool은 Files를 읽거나 쓰고, Repository를 Search하고, Shell Command를 실행하고, git diff를 호출하고, Tests를 시작하고, Compiler를 실행하고, Browser를 조작하고, Database를 Query하거나 External API를 호출할 수 있습니다. MCP를 통해 노출되는 Functions도 이 범주에 들어갈 수 있습니다.

책상 비유에서 Tools는 작업장의 장비입니다.

Write Access가 없는 Model은 File을 어떻게 변경해야 하는지 설명할 수 있습니다. 적절한 Tool이 있으면 Agent는 File을 실제로 열고 수정할 수 있습니다. Test Runner가 있으면 결과를 관찰할 수 있고, Git이 있으면 변경된 Diff를 확인할 수 있습니다.

여기서 또 하나의 중요한 구분이 보입니다.

Skill
=
어떤 Steps가 유용한가?

Tool
=
어떤 수단으로 그 Step을 실행할 수 있는가?

Code Review Skill은 먼저 Diff를 분석하라고 요구할 수 있습니다. git diff나 Repository Tool이 그 Action을 가능하게 합니다.

Debugging Skill은 Reproducible Test로 Hypothesis를 검증하라고 요구할 수 있습니다. Shell과 Test Runner가 실행 능력을 제공합니다.

그래서 Tools는 Skills가 아니고, Skills도 Tools가 아닙니다.

Agent – Task를 끝까지 수행하는 시스템

이제 다시 Agent라는 용어로 돌아가 볼 수 있습니다.

여기에도 단 하나의 Universal Definition은 없습니다. OpenAI는 Agents를 사용자 대신 높은 수준의 자율성을 가지고 Task를 수행하는 시스템으로 설명하며, LLM이 Workflow를 제어하고 Tools가 정보 조회와 Actions를 담당한다고 설명합니다. Anthropic은 더 넓은 의미의 agentic systems라는 표현을 사용하지만, 그 안에서 미리 정의된 Workflows와 Model이 Process와 Tool Use를 동적으로 제어하는 Agents를 구분합니다. [6][7]

경계는 표준화되어 있지 않습니다.

우리의 Mental Model에서는 공통된 아이디어가 더 중요합니다. Agent는 Prompt 하나를 한 번 처리하고 Text 하나를 반환하는 데서 끝나지 않습니다. 여러 Steps에 걸쳐 Task 상태를 보고, 다음 Action을 선택하고, 환경에서 결과를 받고, 그 결과에 반응할 수 있습니다.

단순화하면:

Task
↓
Agent

Model
+ Context
+ Memory
+ Agent Files
+ Skills
+ Tools

↓
Action 선택
↓
실행
↓
결과 관찰
↓
다음 Step 선택
↓
...

모든 Agent가 정확히 이 Components를 가지는 것은 아니고, 모든 시스템이 같은 방식으로 구성하는 것도 아닙니다. Persistent Memory가 없는 시스템도 있고, Skills를 지원하지 않는 시스템도 있으며, 아주 제한된 Tools만 허용하는 시스템도 있습니다.

단일 LLM Call과의 중요한 차이는 새로운 “사고 부품”이 추가되었다는 점보다 Multi-Step Workflow가 조직된다는 데 있습니다.

Coding Agent는 단순한 Model이 아니라 Working Environment 안의 Model입니다.

Coding Agent는 실제로 이 요소들을 어떻게 함께 사용하는가

다음과 같은 평범한 Task를 생각해 봅시다.

Issue 381의 Bug를 수정하고 Regression Test를 추가하라.

Coding Agent는 먼저 Issue를 읽고 Repository를 Search할 수 있습니다. 관련 가능성이 높은 Files를 열고, 해당 Repository 영역의 Local Agent Instructions가 Context에 들어올 수도 있습니다. 오류 분석을 위해 Debugging Skill을 활성화할 수 있습니다.

그다음 기존 Test를 실행하거나 Reproducible Failure를 만들 수 있습니다. Tool은 Error Message를 반환하고, 이 Output은 다음 Working Context의 일부가 될 수 있습니다. Model은 업데이트된 상태를 바탕으로 다음에 어떤 File을 조사하거나 수정할지 결정합니다.

변경 후 Test를 다시 실행합니다. 이번에는 TypeScript Error가 나타날 수도 있습니다. 이 새로운 Observation도 다음 Model Step에 반영될 수 있습니다. Agent는 Patch를 수정하고, 추가 Verification을 수행하고, 마지막으로 Diff를 확인합니다.

전체 흐름은 대략 다음과 같습니다.

Issue
↓
Repository 조사
↓
관련 Files 로드
↓
Agent Files 적용
↓
Debugging Skill 사용
↓
Test 실행
↓
Failure 관찰
↓
Code 수정
↓
Test 재실행
↓
Diff 확인

긴 Prompt 하나도 이 중 많은 Steps를 설명할 수 있습니다. Agent System은 그에 더해 실제 Actions를 조직하고, 결과를 다시 Process에 연결하고, 변화하는 Context를 관리하며, 후속 Model Calls를 조정합니다. 이전 글에서 Coding Benchmarks가 Bare Model만 측정하지 않는다고 했던 이유도 바로 이런 작업 환경 때문입니다.

결국 놀랄 만큼 많은 것이 Context로 들어간다

이제 여러 개념을 다시 하나로 묶어 볼 수 있습니다.

Memory는 현재 Model Invocation 바깥에 저장될 수 있습니다. Agent File은 Repository에 실제 File로 존재합니다. Skill은 Skill Directory에 있다가 필요할 때 활성화될 수 있습니다. Tool은 Model 외부의 Executable Capability로 존재합니다.

Model이 이런 메커니즘의 정보를 활용하려면 관련 Content나 Description이 보통 어떤 형태로든 현재 Context에 들어와야 합니다.

Agent File ─┐
Skill ──────┤
Memory ─────┤
Repository ─┤
Tool Output ┤
            ↓
         Context
            ↓
          Model

그렇다고 이 메커니즘들이 기술적으로 모두 동일한 것은 아닙니다. Lifetime, Selection Rules, Persistence, Priority, Execution Semantics가 크게 다릅니다. 예를 들어 Tool은 계속 External Capability로 존재하고, Model에게 Context가 되는 것은 Tool Description과 Tool Result입니다.

하지만 Demystification 관점에서는 공통된 관찰이 중요합니다.

Agentic AI 주변의 많은 용어는 새로운 종류의 Intelligence를 뜻하지 않습니다. Model에게 정보, Rules, Workflows, 행동 방법을 제공하는 서로 다른 메커니즘을 설명합니다.

Memory System은 무엇을 저장하고 나중에 무엇을 다시 가져올지 결정합니다. Progressive Disclosure는 어느 Skill이 언제 전체적으로 로드되는지에 영향을 줍니다. Agent Files는 Local Rules를 제공합니다. Tools는 Working Environment의 새로운 Observation을 반환하거나 환경을 변경할 수 있게 합니다.

Model은 각 Step에서 이렇게 구성된 Context를 가지고 작업합니다.

간단한 Mental Model

메커니즘	핵심 질문	책상 비유
Model	시스템이 이미 무엇을 할 수 있는가?	교육과 경험
Context	지금 어떤 정보가 사용 가능한가?	책상 위의 자료
Memory	무엇을 저장하고 나중에 다시 찾을 수 있는가?	Archive / Notebook
Agent File	여기서는 어떻게 일하는가?	House Rules
Skill	이런 종류의 작업은 어떻게 수행하는가?	Playbook / 작업 지침
Tool	무엇으로 행동하거나 정보를 가져올 수 있는가?	도구
Agent	이것들이 어떻게 Multi-Step Workflow가 되는가?	작업 조직

모든 비유가 그렇듯이 필요 이상으로 확장하면 안 됩니다. Model은 인간의 교육을 받은 것이 아니고, Memory System은 생물학적 장기기억이 아니며, Agent는 디지털 직원이 아닙니다.

이 표는 역할을 구분하기 위한 것이지 인간의 인지를 재현하려는 것이 아닙니다.

큰 책상만으로 좋은 결과가 나오지는 않는다

겉에서 보면 현대 Coding Agent는 하나의 지능적인 시스템처럼 보이기 쉽습니다. Task를 입력하고 몇 번의 작업 단계를 지켜보다가 마지막에 Patch를 받습니다.

하지만 내부에서는 서로 다른 메커니즘이 함께 작동합니다. Model은 Training에서 얻은 능력을 가지고 있고, Context는 현재 Step에서 사용할 수 있는 정보를 제공합니다. Memory는 정보를 장기간 저장했다가 다시 사용할 수 있게 합니다. Agent Files는 Local Rules를 정의합니다. Skills는 반복 가능한 Workflows를 설명합니다. Tools는 시스템이 환경에서 정보를 가져오거나 Actions를 수행할 수 있게 합니다. Agent는 이 모든 것을 Multi-Step Process로 조직합니다.

이 구분은 단순한 Terminology Pedantry가 아닙니다. 문제의 원인이 어디에 있는지 파악하는 데 도움이 됩니다. Model에 Knowledge가 부족한가? 관련 정보가 Context에 들어오지 않았는가? Memory가 오래되었는가? Agent File이 실제 Architecture와 충돌하는가? Skill Scope가 잘못되었는가? Tool이 없거나 잘못된 Feedback을 주는가?

이 질문들을 나눌 수 있어야 “Agent가 가끔 이상한 짓을 한다”는 말을 기술적으로 조사 가능한 문제로 바꿀 수 있습니다.

특히 Agent Files와 Skills에서는 한 가지 Practical Consequence가 바로 따라옵니다. 다른 Repository는 좋은 아이디어를 줄 수 있지만 우리의 Codebase를 알지는 못합니다. 우리의 Architecture Decisions, Legacy Boundaries, Definition of Done, 실제 Development Workflow도 알지 못합니다.

Agent Files와 Skills는 남의 Best Practices를 복사하는 것만으로는 충분하지 않습니다. 자신의 Codebase와 Working Style에 맞아야 합니다.

큰 책상, Archive, House Rules, Playbooks, Tools만으로도 Coding Agent의 작업 환경 대부분을 설명할 수 있습니다. 하지만 아직 중요한 특징 하나가 남아 있습니다. 같은 Agent에게 같은 Context, 같은 Rules, 같은 Skills, 같은 Tools를 주더라도 매번 정확히 같은 Solution을 얻는 것은 아닙니다.

기반 Model은 확률적으로 작동합니다. 왜 이것이 결과의 차이를 만들고, Software Engineering에서는 무엇을 의미하는지 다음 글에서 살펴보겠습니다.

참고 자료

[1] AGENTS.md: A simple, open format for guiding coding agents. 2026년 9월 기준 Project Documentation. AGENTS.md를 Build Steps, Tests, Conventions, 기타 Project-specific Context를 위한 예측 가능한 위치로 설명합니다.

[2] GitHub: Adding repository custom instructions for GitHub Copilot. GitHub Docs, 2026년 9월. .github/copilot-instructions.md, Path-specific .instructions.md, 그리고 AGENTS.md, CLAUDE.md, GEMINI.md를 Agent Instructions로 사용하는 방법을 설명합니다.

[3] Anthropic: How Claude remembers your project. Claude Code Docs, 2026년 9월. CLAUDE.md, .claude/rules/, Auto Memory, Context로 로드되는 방식, 기존 AGENTS.md Instructions를 Import하는 방법을 설명합니다.

[4] Agent Skills: Agent Skills Overview, Specification, How to add skills support to your agent. Open Agent Skills Standard, 2026년 9월. 원래 Anthropic이 개발한 Format으로 SKILL.md, Optional Scripts, References, Assets, Discovery·Activation·Execution 단계의 Progressive Disclosure를 설명합니다.

[5] Matt Pocock: Skills for Real Engineers. GitHub Repository, 2026년 9월. TDD, Debugging, Code Review, Implementation, Research, Domain Modeling 등을 위한 Engineering Skills Collection.

[6] Erik Schluntz, Barry Zhang / Anthropic: Building effective agents. Anthropic, 2024년 12월 19일. 미리 정의된 Workflows와 LLM이 Process와 Tool Use를 동적으로 제어하는 Agents를 구분합니다.

[7] OpenAI: A practical guide to building agents. Agents를 사용자 대신 높은 수준의 독립성을 가지고 Task를 수행하며, LLM이 Workflow Execution과 Tool Selection을 제어하는 시스템으로 설명합니다.

[8] Anthropic: Effective context engineering for AI agents. Anthropic Engineering, 2025년 9월 29일. 순수 Pre-Inference Retrieval에서 벗어나 Agents가 실행 중 필요한 Context를 동적으로 불러오는 “just in time” 전략 등을 설명합니다.