프로젝트 셋팅을 잘 해야 하는 이유

클로드 코드, 코덱스, 헤르메스 에이전트, 오픈클로 등 여러 에이전트를 사용하다 보면 SOUL.md, AGENTS.md, CLAUDE.md 와 같은 파일들을 셋팅 해야 한다는 이야기를 주변에서 많이 듣게 됩니다. 

하지만, 이 파일들은 도대체 무엇을 하는 파일이고 정확하게 "어떻게 내 프로젝트에 영향을 줄 수 있지?" 라는 고민들이 머릿속에서 정리되지 않은 상태로 그냥 AGENT 에게 이 파일들을 적어달라고 하는 경우가 대부분 입니다.

그래서 오늘은 이 파일들이 도대체 무엇인지, 그리고 여러분들이 어떻게 잘 셋할 수 있는지 가이드를 적어보려고 합니다.

우리가 프로젝트를 셋팅하던 방식

기존에 사람과 협업할때 프로젝트를 셋팅하던 방식을 먼저 생각해 봅시다. 일단 새 프로젝트를 시작하기 위해 문서들을 정리하기 위한 폴더를 만들고, 그 폴더 하위에 작업 내용을 채우기 시작합니다

이후에 새로운 팀원이 회사에 올 기간이 얼마 안 남았다고 해보죠. 이 팀원이 빠르게 팀에 적응하기 위해서는 어떻게 하는 것이 좋을까요? 아마도 문서로 팀원이 어떻게 일해야 하는지 알려주고, 이를 우리가 1:1 로 붙어서 가이드를 하는 것이 좋을 것입니다.

에이전트들도 마찬가지입니다. 에이전트를 위한 온보딩 문서인 AGENTS.md(또는 CLAUDE.md) 를 작성하고, 이 프로젝트에서 어떻게 작업을 해야 하는지 알려줍니다.

아마, 이정도로도 감이 안오실수 있는데요. 제가 실제로 제 편집자로 고용중인 헤르메스 에이전트 에게 제공한 온보딩 문서의 예시를 적어볼게요.

# 편집 규칙

1. 박수소리는 컷 편집 지점이다. 보통 박수 소리의 시작 ~ 끝 기준으로 편집점을 잡으면 된다. 박수소리(clap)는 절대로 영상에 등장해서는 안된다.
2. 영상 맨 앞, 뒤 근방에 OBS 화면은 절대로 영상에 나와서는 안된다.
3. 너무 긴 묵음 구간(10 초 이상)이 있다면 앞, 뒤 판단해서 자연스럽게 중간 묵음 구간을 컷 편집해서 이어 붙여주세요.

## 전사(Transcription)

1. 전사할때는 Minimax 를 이용해주셔도 됩니다. .env 파일에 MINIMAX_API_KEY 가 저장되어 있어요.
-> 참고: https://platform.minimax.io/docs/api-reference/api-overview

## Youtube Shorts

1. 긴 편집본 영상에서 쇼츠를 만들 때는 30~60초 길이의 일관된 주제/맥락을 가진 구간을 고르세요. 단순히 고정 길이로 자르지 말고, 후킹이 될 만한 발화나 장면을 기준으로 판단합니다.
2. 출력은 Youtube Shorts 규격인 1080x1920 세로 9:16 MP4로 만듭니다. 최종 파일은 `편집본/shorts/` 아래에 저장하고, 전사/ASS/검증용 이미지 등 중간 산출물은 `작업tmp/<작업명>/` 아래에 둡니다.
3. 16:9 화면 녹화본을 쇼츠로 만들 때 중요한 UI가 잘리지 않도록 중앙 크롭만 하지 마세요. 원본 영상을 가로폭 기준으로 중앙에 배치하고, 뒤쪽 배경은 같은 영상을 세로 화면에 맞게 블러/어둡게 확장하는 구성을 우선합니다.
4. 반드시 전사하여 한국어 자막을 영상에 burn-in 합니다. 자막은 Youtube 쇼츠에서 자주 보이는 스타일처럼 화면 상단에 살짝 마진을 두고 배치합니다.
5. Windows 기준 자막 기본값은 굵은 `Malgun Gothic`(맑은 고딕), 검정 글자, 두꺼운 흰색 외곽선입니다. 전사 오류는 문맥상 명백한 경우 정리합니다. 예: 헤르메스, 컷 편집, Qwen, FFmpeg, YOLO.
6. 렌더링 후 `ffprobe`로 해상도 1080x1920, 오디오 포함, 길이 30~60초를 확인하고, `silencedetect`로 쇼츠에 부적절한 긴 묵음이 없는지 확인합니다. 필요하면 contact sheet를 만들어 화면 구성을 확인합니다.

## Thumbnail 생성

현재 codex 의 image gen tool 을 붙여 놓은 생성입니다. 코덱스의 이미지 생성으로만 반드시 썸네일을 생성해주세요. 당신이 텍스트를 어느 위치에 놓고 이런걸 하고 싶을 수 있는데, 그것 마져 프롬프트로 구성해서 이미지 생성을 해주세요.

그리고 썸네일 폴더 아래에 me.jpg 가 있는데 그게 제 mascot 이미지 입니다. 이것도 항상 포함시켜주세요.

Youtube 는 조금 hooking 이 될만한 썸네일로 만들어주셔야 합니다. 항상 썸네일 만들기 전에 저에게 Title 을 뭘로 할 건지에 대해 질문해주세요. 제가 알려드릴게요. 그거 기반으로 Thumbnail 을 만들어주세요.

위 문서를 차근차근 읽어보면 제가 영상을 찍으며 중간에 컷편집 구간을 잡기 위한 박수소리, 그리고 에이전트의 응답을 기다리느라 긴 묵음 구간이 생기는 구간에 대한 편집 처리에 대한 부분이 담겨 있습니다.

즉, 에이전트에게 "우리는 기존에 어떤 영상을 편집하고 있었고, 이 영상들의 특징은 이것이므로 이렇게 행동해야 해!" 라고 온보딩 문서에 적어 놓는 것입니다. 이렇게 적어 두면, 에이전트가 이 온보딩 문서를 작업에 들어가기전에 반드시 한번 읽고 작업에 들어가게 됩니다.

그런데 에이전트는 어떻게 이 파일을 알아서 읽는 걸까요? 아니면 우리가 넣어줘야만 읽는걸까요? 이걸 이해하기 위해 에이전트(클로드 코드, 코덱스, 헤르메스, 오픈클로, etc) 가 어떻게 작업을 시작하는지 한번 알아볼게요.

에이전트들은 어떻게 작업을 시작할까?

우리가 특정 디렉토리에서 에이전트를 불러 작업을 한다고 가정해 봅시다. 우리는 단순하게 "에이전트야 나만의 웹페이지 만들어줘" 라고 입력하는 것 같지만, 이 하부에서는 꽤나 많은 일들이 일어납니다. 

꽤나 많은 일들이 일어나지만, 오늘은 AGENTS.md, SOUL.md 와 같은 파일들을 어떻게 읽는지 살펴볼게요

일단 에이전트는 온보딩 파일인 AGENTS.md(CLAUDE.md) 를 읽기 시작해요. 온보딩 문서를 읽으면서 아래와 같은 내용들을 확인하게 됩니다.

온보딩 문서를 읽고나면 유저가 입력한 명령과 함께 프롬프트를 다시 재 생성하게 됩니다. 유저가 입력한 명령과 AGENTS.md 파일이 더해져서 프롬프트가 구성해서 실제 모델로 전달되게 되요.

즉, 우리는 프롬프트 한줄만 입력한 것 같지만 실제 에이전트의 뇌에는 AGENTS.md 파일도 같이 들어가게 된 것이죠. 그래서 AGENTS.md 파일을 우리 프로젝트에 맞게 잘 적어두면 항상 에이전트에게 입력되게 되요. 하나의 에이전트만을 위한 온보딩 문서가 완성된 것이죠. 

그렇다면 이 파일을 어떻게 잘 관리하고 잘 적을 수 있을까요?

AGENTS.md 잘 적는법

위에서 설명한 것과 같이 어찌보면 AGENTS.md 는 에이전트의 컨텍스트(Context) 를 차지하는 프롬프트의 일부에요. 최근에 컨텍스트 엔지니어링(Context Engineering) 이라는 말이 핫했잖아요? 

AGENTS.md 파일 또한 컨텍스트의 일부이므로 우리는 이를 어떻게 잘 다뤄야 할지 엔지니어링을 해야할 필요가 있어요.

https://x.com/mattpocockuk

해외에서 유명한 테크 인플루언서인 맷 포칵(matt pocock) 은 이런 말을 남겼어요.

즉, AGENTS.md 파일도 컨텍스트에 들어가므로, 모든 제약사항을 명시하기 보다 상황에 따라 필요한 제약사항만 읽게 하라는 것이죠. 이를 점진적 공개(Progressive Disclosure)^[1]​ 라고 불러요. 나중에 추후 시리즈에서 내용에 관련해서도 더 자세하게 설명해볼게요.

실제로도 에이전트가 긴 지침을 얼마나 잘 따르는지 실험한 연구^[2]​들을 보면, 지침이 길고 복잡해질수록 모델이 놓치는 내용이 많아진다고 해요. 그래서 AGENTS.md 는 “많이 적기”보다 “필요한 내용을 잘 나눠두기”가 더 중요합니다.

하나의 비용(Instruction budget) 으로 생각하고, 최소한 컴팩트 하게 500자 내외로 유지하되 프로젝트에 관한 기본적인 내용을 담아야 해요.

그렇다면 여기에는 어떤 내용이 담기면 좋을까요?

AGENTS.md 에 담기면 좋은 내용들

목적 적기

첫번째로는 이 프로젝트가 어떤 프로젝트 인지 알려주면 좋아요. 에이전트는 매번 새로운 뇌를 가지고 태어나므로, 우리 프로젝트에 대한 간단한 설명을 해주면 좋습니다.

## 목적
이 프로젝트는 신규 유저가 우리 서비스를 처음 이해할 수 있도록 돕는 온보딩 콘텐츠를 만드는 작업입니다.

독자는 우리 서비스를 처음 접하는 비개발자이며, 어려운 기술 용어보다 실제 사용 상황 중심의 설명을 선호합니다.

위와 같이 일단 우리 프로젝트가 어떤 프로젝트인지 적어 놓으면 조금 더 에이전트가 온보딩 하는데 크게 도움이 많이됩니다.

반드시 해야할 것 / 하지 말아야 할 것 명시

에이전트는 자신이 학습될때 만들어진 지식을 기반으로 답변을 진행하기 때문에, 우리 프로젝트에서 반드시 지켜야 할 것과 하지 말아야 할것을 명시해 주는 것이 좋습니다. 보통은, 일반적으로 다른 기업들과 비슷할 수 있지만, 약간 다른 경우 에이전트가 이런 미세한 디테일을 인식하지 못하기 때문이에요

## 작업할 때 지켜야 할 톤

- 초보자도 이해할 수 있게 쉽게 설명하세요.
- 어려운 용어가 필요하면 먼저 쉬운 말로 풀어 설명하세요.
- 너무 홍보 문구처럼 쓰지 말고, 실제 사용자가 겪는 문제에서 출발하세요.
- 문장은 짧게 쓰고, 한 문단에는 하나의 이야기만 담으세요.

## 반드시 확인해야 할 것

- 이 글을 읽는 사람이 누구인지 먼저 확인하세요.
- 사용자의 현재 수준을 가정하지 말고, 필요한 배경 설명을 포함하세요.
- 예시는 개발자 예시보다 일상적인 업무 예시를 우선 사용하세요.
- 최종 결과물은 바로 복사해서 문서나 블로그에 붙일 수 있는 형태로 작성하세요.

## 하면 안 되는 것

- 독자가 모를 만한 전문 용어를 설명 없이 쓰지 마세요.
- 기능 목록만 나열하지 마세요.
- “혁신적인”, “강력한”, “최고의” 같은 추상적인 홍보 표현을 남발하지 마세요.
- 요청받지 않은 방향으로 글의 주제나 타겟 독자를 바꾸지 마세요.

이렇게 어떻게 출력결과를 내야 하는지, 우리 프로젝트에서 반드시 확인해야 할 것은 무엇인지 이런 디테일한 부분에 대해서 서술해 놓으면 좋습니다

상황에 따라 필요한 디테일 문서 정의

예를 들면, 브랜드 관련된 문서를 적을때, 그리고 온보딩 관련된 문서를 적을때 사용되어야 하는 지침이 다르다고 가정 해봅시다. 이때는 "AGENTS.md 에 각기 다른 지침을 적어두어야 하나?" 라는 생각이 들게 되는데요.

왜냐면 거대 언어 모델(LLM) 특성상 필요 없는 정보를 보여주지 않는 것이 작업에 꽤나 큰 도움을 주기 때문^[3]​입니다. 그래서 브랜드 관련 문서에 대한 작업을 할때는, 온보딩에 대한 어투 이런것들이 에이전트의 컨텍스트에 있으면 오히려 작업에 방해가 되게 됩니다.

그래서 이때는 위에서 언급한 점진적 공개(Progressive Disclosure) 기법을 사용하시면 좋아요. 말은 어려워 보이지만 아래와 같이 적는 방식이에요.

- 브랜드 톤앤매너는 `docs/brand-tone.md`를 참고하세요.
- 자주 쓰는 용어는 `docs/glossary.md`를 참고하세요.
- 콘텐츠 작성 규칙은 `docs/content-guide.md`를 참고하세요.

이렇게 하게 되면 에이전트가 현재 하고 있는 작업과 연관된 파일만 열어서 보게 되고, 다른 내용들은 에이전트의 컨텍스트 내용에 방해가 되지 않아 더 일관적이고 뛰어난 작업 결과를 보이게 됩니다

마치며

오늘은 AGENTS.md 에 대해서 알아보았는데요. 강조하자면, AGETNS.md 파일은 우리가 에이전트와 함께 더 잘 일하기 위한 에이전트용 온보딩 문서이고, 이 문서를 잘 가꾸고 나아가야만 에이전트도 더 잘 일할 수 있게 된다는 점을 배워봤어요.

다음에는 SOUL.md 와 실제 현업 수준에서의 자동화에 대한 내용을 조금 다뤄보려고 합니다. 

계속해서 좋은 인싸이트를 받아보고 싶으시다면 뉴스레터를 구독해주세요! 😊