Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
본 문서는 코딩 에이전트가 지침, 컨텍스트 저장, 학습 및 개발 원칙을 따르는 5가지 구성 요소를 설명합니다. 특히 'Skills'는 회사 표준 운영 절차(SOP)와 같은 역할을 하며, 에이전트에게 특정 작업 수행 방법을 가르치는 재사용 가능한 업무 매뉴얼입니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기본 문서는 제가 사용하는 코딩 에이전트 워크플로우의 다섯 가지 주요 구성 요소를 설명합니다. 목적은 간단합니다. 에이전트가 어떻게 지침을 받고, 컨텍스트를 저장하며, 작동 방식을 학습하고, 소프트웨어 개발 원칙을 따르는지 이해하는 것입니다.
기술적인 전문 용어부터 시작할 필요는 없습니다. 개념을 더 쉽게 이해하기 위해 직장인, 매뉴얼 북, 그리고 로그북의 비유를 사용하겠습니다.
참고: 본 문서는 일반적인 코딩 에이전트 개념과 저의 개인 설정을 결합한 것입니다. 모든 에이전트가 동일한 메커니즘이나 파일 구조를 가지고 있지는 않습니다. 기술적 세부 사항은 각 에이전트의 공식 문서를 참조해야 합니다.
AI 에이전트를 매우 똑똑하지만, 우리 회사에서 어떻게 일하는지 모르는 신입 사원이라고 상상해 보세요.
그는 코드를 작성하고, 지침을 이해하며, 문제를 해결할 수 있습니다. 하지만 다음은 알지 못할 수도 있습니다:
Skills는 에이전트에게 우리가 원하는 방식대로 특정 작업을 수행하는 방법을 가르치는 매뉴얼입니다.
| 항목 | Extension / Tool (확장 기능/도구) | Skill (스킬) |
|---|---|---|
| 기능 | 무언가를 할 수 있는 능력을 제공함 | 무언가를 하는 방법에 대한 지침을 제공함 |
| ... |
간단한 예시:
Extension 또는 tool은 에이전트에게 Git을 사용할 수 있는 '손'을 제공합니다. 반면, Skill은 우리가 원하는 방식으로 커밋 메시지를 작성하는 방법을 가르쳐줍니다.
PiG에서 스킬의 한 형태는 skill 디렉토리에 저장된 SKILL.md 파일입니다.
예시:
~/.pig/skills/commit/SKILL.md
파일 내용은 스킬의 이름, 사용 목적, 그리고 따라야 할 지침을 설명할 수 있습니다.
간단한 예시:
---
name: commit
description: 프로젝트 형식에 맞춰 커밋 메시지 작성.
...
에이전트가 해당 스킬을 발견하면, 필요한 시점에 제공된 정보와 지침을 사용할 수 있습니다.
스킬의 로드 및 사용 방법은 에이전트 구현체에 따라 다릅니다. 모든 에이전트가 세션 시작 시마다 각 스킬의 전체 내용을 읽는다고 가정해서는 안 됩니다.
PiG는 --skill 옵션을 사용하는 것을 포함하여, 지원되는 디렉토리로부터의 검색(discovery) 메커니즘을 통해 스킬 로드를 지원합니다.
예시:
pig --skill commit
사용되는 디렉토리는 해당 PiG 버전에 의해 지원되는 구조와 구성을 따라야 합니다.
스킬이 없다면, 우리는 동일한 작동 방식을 반복적으로 설명해야 할 수도 있습니다.
스킬을 사용하면 이러한 가이드를 저장하고 재사용할 수 있습니다.
이는 사람 직원을 위한 SOP(Standard Operating Procedure)와 같습니다.
요약: 스킬은 에이전트가 우리가 원하는 작업 방식을 따를 수 있도록 하는, 재사용 가능한 특정 업무 지침입니다.
스킬이 특정 작업에 대한 가이드라면, AGENTS.md는 프로젝트 내에서 작동하는 에이전트에게 일반적인 규칙과 지침을 설정하는 데 사용될 수 있습니다.
예를 들어, 작업을 시작하기 전에 우리는 에이전트가 다음 규칙을 이해하길 원합니다:
이러한 지침은 프로젝트 지침 파일에 배치하는 것이 적절합니다.
저의 워크플로우에서는 그 내용이 몇 가지 항목을 포함합니다.
| 부분 | 의미 |
|---|---|
| Global Principles | 보안 및 백업과 같은 기본 원칙 |
| ... | |
| 이는 제가 자체적으로 워크플로우를 관리하기 위해 사용하는 배열이며, 모든 코딩 에이전트에게 필수적인 형식은 아닙니다. |
에이전트가 프로젝트 디렉토리의 모든 Markdown 파일을 읽는 것은 아닙니다.
일반적으로 에이전트는 알려진 지침 파일을 찾기 위한 특정 메커니즘을 가지고 있습니다. PiG는 자체적인 컨텍스트 로딩 규칙을 가지며, KiloCode 역시 고유한 지침 및 구성 메커니즘을 가지고 있습니다.
따라서 Agent.md, AGENTS.md 또는 CLAUDE.md와 같은 이름의 파일이 모든 에이전트에 의해 동일한 방식으로 처리될 것이라고 가정해서는 안 됩니다.
특정 지침 파일을 사용하려면, 사용 중인 에이전트의 문서를 확인하고 해당 파일이 실제로 로드되는지 확인해야 합니다.
에이전트 컨텍스트에 지속적으로 포함되는 지침은 사용 가능한 토큰 일부를 차지합니다.
그래서 저는 중요한 일반 규칙을 메인 지침 파일에 배치하는 것을 선호합니다. 특정 작업에 대한 자세한 가이드는 별도의 스킬(skills) 또는 참조 문서에 보관할 수 있습니다.
요약: AGENTS.md는 에이전트의 지침과 작업 경계를 설정하는 곳입니다. 내용이 명확하고, 관련성이 있으며, 사용 중인 에이전트에 의해 실제로 읽히도록 해야 합니다.
대화 세션이 끝나면, 에이전트는 다음 세션에 필요한 전체 작업 컨텍스트를 더 이상 가지고 있지 않을 수 있습니다.
우리가 Laravel 시스템을 개발한다고 가정해 봅시다. 데이터베이스를 확인하고, 여러 파일을 수정했으며, 하나의 문제를 식별했습니다. 그리고 내일, 새로운 세션을 시작합니다.
컨텍스트가 저장되지 않으면, 우리는 동일한 검사를 반복해야 할 수도 있습니다.
이곳에서 brain/ 개념이 유용해집니다.
제 워크플로우에서 brain/는 에이전트가 다음 세션에 다시 참조할 수 있는 작업 기록을 저장하는 디렉토리입니다.
이는 AI 모델이 갑자기 영구적인 기억을 갖게 된다는 의미는 아닙니다. 그 정보는 우리가 파일에 저장하고, 에이전트에게 이를 재참조하도록 지시함으로써 유지되는 것입니다.
엔지니어의 작업 일지는 보통 다음 내용을 기록합니다:
동일한 개념이 brain/에서도 사용됩니다.
다음은 제가 업무 관례로 사용하는 구조의 예시입니다:
brain/
├── task.md
├── walkthrough.md
...
각 파일의 기능:
| 파일 | 용도 |
|---|---|
task.md | 작업 상태, 현재 문제점 및 다음 단계 |
| ... | |
| 이 구조는 PiG나 KiloCode의 필수 구조가 아닙니다. 프로젝트에 따라 맞춤 설정 가능한 문서화 디자인입니다. |
제가 사용하는 한 가지 아이디어는 'Mental Anchor'입니다.
세션 기록 끝에서 에이전트는 작업을 이어갈 정확한 위치를 명시해야 합니다.
예시:
## 현재 상태
- 마이그레이션(Migration)을 검토했습니다.
...
Mental Anchor는 에이전트가 다음 세션을 시작할 적절한 출발점을 알도록 돕습니다.
다만, 이 기록은 실제 저장소(repository)의 상황과 여전히 확인되어야 합니다. 기록 작성 후 파일은 변경될 수 있습니다.
저는 전역적인 기록과 특정 프로젝트에 대한 기록을 구분합니다.
| 종류 | 예시 위치 | 목적 |
|---|---|---|
| 글로벌 (Global) | ~/.config/kilo/brain/ | 워크플로우의 원칙 및 일반적인 기록 |
| 프로젝트 (Project) | <프로젝트>/.agents/brain/ | 특정 프로젝트의 컨텍스트 및 상태 |
이 위치는 PiG나 KiloCode가 자동으로 읽도록 보장하는 표준 위치가 아니라 저의 개인적인 관례입니다.
에이전트는 정확한 위치를 읽도록 지시받아야 합니다. 만약 전역 기록과 프로젝트 기록이 모두 존재한다면, 컨텍스트 충돌을 방지하기 위해 우선순위 규칙도 설정되어야 합니다.
요약: brain/은 에이전트가 해당 기록을 올바르게 읽고 업데이트한다는 전제 하에, 세션 간 컨텍스트를 유지하는 작업 노트 시스템입니다.
만약 AGENTS.md가 작업 지침과 경계를 설명한다면, ai_guidelines.md는 나의 작업 방식에 대한 가이드라인이 되는 원칙들을 설명합니다.
이는 마법의 설정 파일이 아닙니다. AI의 도움을 받아 소프트웨어 개발 시 내가 유지하고 싶은 원칙들을 담고 있는 문서입니다.
AGENTS.md: 빨간불에 멈춰라.ai_guidelines.md: 나는 빨리 도착하는 것보다 안전이 더 중요하다고 믿는다.전자는 지침을 설정합니다. 후자는 우리가 일하는 방식의 근본 원칙을 설명합니다.
나의 워크플로우에서 중요한 원칙들은 다음과 같습니다:
1. 인간이 이해하고 책임진다 (Human understanding and responsibility)
AI는 해결책을 제공하는 데 도움을 주지만, 최종 결정에 대해서는 내가 이해하고, 확인하며, 책임을 져야 합니다.
2. 단순한 코드가 지나치게 복잡한 코드보다 낫다 (Simple code beats over-clever code)
읽고 유지보수하기 쉬운 해결책이 보기에는 멋지지만 이해하기 어려운 코드보다 일반적으로 더 적합합니다.
3. 보안은 설계 단계부터 시작되어야 한다 (Security by design)
보안은 시스템 구축이 끝난 후 추가되는 작업이 아닙니다. 개발 초기 단계부터 고려되어야 합니다.
4. 변경 전에 확인한다 (Verify before changing)
에이전트는 변경을 가하기 전에 프로젝트의 실제 상태를 이해해야 합니다. 검토 없이 구조, 의존성(dependency) 또는 구성을 가정해서는 안 됩니다.
5. Git과 배포(deployment)는 항상 인간의 통제 하에 있다 (Git and deployment remain under human control)
Agent는 변경 사항을 제공하고, 테스트를 실행하며, 결과를 보고할 수 있습니다. 저의 워크플로우에서는 커밋(commit), 푸시(push), 배포(deploy)에 대한 결정은 여전히 사람의 손에 달려 있습니다.
6. 불확실할 때는 솔직하게 말하기
만약 어떤 지침이 실패하면, 에이전트는 작업이 완료되었다고 주장하는 대신 그 실패를 보고해야 합니다.
AI는 보조합니다. 저는 이해하고, 검증하며, 최종 결정에 대한 책임을 집니다.
이 문서는 에이전트가 제가 우선시하는 개발 접근 방식을 이해해야 할 때 참조할 수 있습니다. 이것이 실제로 사용되도록 하려면, 주요 지침은 에이전트에게 언제 그리고 어떻게 이 파일을 읽어야 하는지 알려주어야 합니다.
요약: ai_guidelines.md는 AI의 도움을 받아 소프트웨어를 개발할 때 제가 유지하고 싶은 원칙과 작업 접근 방식에 대한 참고 자료입니다.
만약 ai_guidelines.md가 작업 원칙의 요약을 제공한다면, soul.md는 저의 워크플로우에서 이러한 원칙을 더 깊이 설명하는 데 사용됩니다.
soul.md라는 이름은 에이전트가 인간처럼 영혼이나 의식을 가지고 있다는 의미가 아닙니다. 이것은 제가 에이전트의 철학과 설계 목적을 저장하기 위해 선택한 파일 이름입니다.
| 파일 | 주요 질문 | |
|---|---|---|
AGENTS.md | 저의 지침과 작업 범위는 무엇인가요? | |
| ... | ||
| 쉬운 비유: |
AGENTS.md는 규칙서입니다.ai_guidelines.md는 책상 위의 간단한 메모입니다.soul.md는 그러한 원칙의 배경에 있는 이유를 설명하는 문서입니다.제 설계에서 이 문서는 다음과 같은 원칙을 포함합니다:
이러한 원칙들은 내가 구축하고자 하는 워크플로우의 정체성을 형성하며, 특정 모델에서 자동으로 보장되는 기능은 아닙니다.
내 워크플로우에서 에이전트의 작업은 다음 주기를 따릅니다:
Understand
↓
Inspect
...
즉: