지난주 제가 OpenClaw 작업 공간에서 작업하면서 이런 경험을 했습니다. 에이전트는 올바른 파일, 올바른 도구, 그리고 올바른 프로젝트 컨텍스트에 접근할 수 있었지만, 유용한 동작은 어떤 마법 같은 프롬프트 하나에서 나온 것이 아니었습니다. 그것은 여러 개의 지속 가능한 지침으로 이루어진 작은 스택에서 나왔습니다.

최상위 AGENTS.md 파일에는 무엇을 먼저 읽어야 하는지가 적혀 있었습니다. SOUL.md는 어시스턴트의 운영 자세를 정의했습니다. USER.md는 개인적인 컨텍스트를 제공했습니다. TOOLS.md는 재사용 가능한 도구 동작과 로컬 머신 세부 사항을 분리했습니다. 스킬 문서(Skill docs)는 언제 전문화된 워크플로우를 불러와야 하는지 설명했습니다.

이러한 구조는 저에게 여러 번 유용하다는 것을 입증해 왔습니다.

현재 Linux Foundation이 호스팅하는 Agentic AI Foundation 생태계의 일부인 AGENTS.md는 개발자가 코딩 에이전트에게 리포지토리(repo) 내에서 어떻게 작업해야 하는지를 알려주는 단순한 Markdown 공간을 제공합니다. 형식은 의도적으로 간단합니다. 어려운 부분은 파일 자체가 아닙니다. 어려운 부분은 여기에 무엇을 담을 가치가 있는지 결정하는 것입니다.

첫 5분부터 시작하세요

좋은 AGENTS.md는 먼저 하나의 질문에 답해야 합니다. 에이전트가 코드를 만지기 전에 무엇을 해야 할까요?

제 작업 공간에서는 시작 경로가 명시적입니다:

1. SOUL.md 읽기
2. USER.md 읽기
3. 오늘과 어제의 일일 메모 파일 읽기
4. 메인 세션에서 MEMORY.md 읽기

이것은 에이전트에게 부팅 순서를 제공합니다. 어떤 파일이 중요한지, 메모가 허용되는지, 또는 개인 컨텍스트가 공유 채팅에 속하는지에 대해 추측할 필요가 없습니다.

대부분의 리포지토리 지침은 이 부분을 건너뜁니다. 그들은

운영 규칙으로부터 정체성 분리하기

여러분의 리포지토리(repository)에 아마 SOUL.md 파일이 필요하지는 않겠지만, 이 패턴은 유용합니다. 하나의 파일로 작업 자세(working posture)를 정의하고, AGENTS.md로 프로젝트의 동작(behavior)을 정의할 수 있습니다.

소프트웨어 리포지토리의 경우, 다음과 같은 모습일 수 있습니다:

## 작업 자세 (Working posture)

- 새로운 추상화(abstractions)를 제안하기 전에 기존 코드를 먼저 읽으세요.
...

이것들은 판단 규칙(judgment rules)입니다. 이러한 규칙은 이후의 모든 결정에 영향을 미치기 때문에 파일의 상단에 위치해야 합니다.

그다음, 리포지토리 특유의 메커니즘(mechanics)은 다른 곳에 배치하세요:

## 명령어 (Commands)

- 의존성 설치: `pnpm install`
...

왜 이를 분리해야 할까요? 명령어는 원칙(principles)보다 더 빠르게 변하기 때문입니다. 모든 것을 한데 섞어버리면 파일은 잡동사니 서랍(junk drawer)이 되어버립니다. 에이전트(Agents)가 여전히 이를 읽기는 하겠지만, 어떤 지침이 동작을 제어하고 있는지 알 수 없게 됩니다.

에이전트가 실수할 만한 곳에 경계 설정하기

제 작업 공간의 AGENTS.md에서 가장 훌륭한 문구는 짧습니다: trash > rm.

이것은 단 세 개의 토큰(tokens)으로 로컬 안전 규칙을 가르칩니다. 파괴적인 삭제는 복구 가능해야 한다는 것을 의미합니다. 유닉스 철학(Unix philosophy)을 설명하거나 훈계하지 않습니다. 에이전트가 행동하는 동안 적용할 수 있는 규칙을 제공할 뿐입니다.

여러분의 AGENTS.md에도 이와 같은 경계(boundaries)를 포함해야 합니다:

## 레드라인 (Red lines)

- 생성된 파일을 직접 수정하지 마세요.
...

그 형태를 주목하세요: 구체적인 동사, 구체적인 대상, 구체적인 제한 사항입니다.

"데이터를 조심해서 다루세요"는 너무 모호합니다. "공유 데이터베이스에 대해 마이그레이션(migrations)을 실행하지 마세요"는 에이전트가 준수할 수 있는 무언가를 제공합니다.

컨텍스트 접근 규칙 가르치기

에이전트는 종종 너무 적게 읽거나 너무 많이 읽음으로써 실패합니다. 리포지토리 지침은 이 두 가지 문제를 모두 해결할 수 있습니다.

제 워크스페이스에서 MEMORY.md는 공유 컨텍스트가 아닌 메인 세션에서만 로드됩니다. 이는 개인정보 보호 규칙인 동시에 컨텍스트 규칙이기도 합니다. 데일리 노트 (Daily notes)는 가공되지 않은 로그이며, 장기 기억 (Long-term memory)은 큐레이션된 것입니다. TOOLS.md는 환경 특화적인 노트를 위한 것이며, 기술 (skills)은 재사용 가능합니다.

이러한 구조는 흔히 발생하는 문제, 즉 지속적인 지침 (durable instructions)이 언젠가 누군가에게 필요할지도 모르는 모든 사실을 쏟아붓는 쓰레기통이 되는 문제를 방지합니다.

팀 리포지토리의 경우, 동일한 분할 방식을 사용할 수 있습니다:

## Context files

- `README.md`: 인간을 위한 설정 및 프로젝트 개요.
...

마지막 문장이 중요합니다. 그것은 에이전트에게 지도의 끝이 어디인지를 알려줍니다.

공유 기술에서 로컬 세부 사항 제외하기

제 워크스페이스의 TOOLS.md는 명확한 구분을 둡니다. 기술 (skills)은 도구가 어떻게 작동하는지를 정의하고, TOOLS.md는 카메라 이름, SSH 별칭 (aliases), 스피커 또는 선호하는 음성과 같은 로컬 세부 사항을 저장합니다.

이는 엔지니어링 팀에도 잘 적용됩니다.

재사용 가능한 지침은 다음과 같이 말할 수 있습니다:

CI를 디버깅할 때, 코드를 변경하기 전에 실패한 작업 로그를 검사하세요.

로컬 지침은 다음과 같이 말할 수 있습니다:

스테이징 대시보드는 <internal URL>에 있습니다.

이것들은 같은 곳에 있어서는 안 됩니다. 재사용 가능한 지침은 프로젝트 간에 이동할 수 있습니다. 로컬 세부 사항은 유출되어서는 안 되며, 더 빠르게 노후화됩니다.

이것이 AGENTS.md가 AAIF 프로젝트 세트 내에 자연스럽게 어울리는 이유 중 하나입니다. MCP는 에이전트가 도구에 연결되는 방식을 설명합니다. agentgateway는 에이전트 트래픽의 라우팅 및 거버넌스 (governing)를 담당합니다. AGENTS.md는 리포지토리 수준의 동작을 처리합니다. 각 도구가 자신만의 사적인 관습을 만들어내지 않고도 에이전트가 프로젝트 전반에서 작동하려면 이 모든 계층이 필요합니다.

양이 아닌 깊이를 위해 기술 사용하기

제 워크스페이스에는 다음과 같이 명시되어 있습니다: "기술 (Skills)은 도구를 제공합니다. 도구가 필요할 때는 해당 SKILL.md를 확인하세요."

그것이 올바른 분업입니다. AGENTS.md는 에이전트를 더 깊은 지침으로 안내하는 역할을 해야 합니다. 모든 워크플로우 (workflow)에 대한 전체 매뉴얼을 포함해서는 안 됩니다.

나쁜 예:

## 릴리스 프로세스 (Release process)

[900줄에 달하는 릴리스 규칙, 변경 로그 정책, 패키지 레지스트리 참고 사항, 롤백 단계, 커뮤니케이션 템플릿 및 예외 케이스]

좋은 예:

## 릴리스 프로세스 (Release process)

릴리스 작업을 수행할 때는 변경 사항을 적용하기 전에 `skills/release/SKILL.md`를 읽으세요. 사용자가 명시적으로 요청하지 않는 한 패키지를 게시하거나 GitHub 릴리스를 생성하지 마세요.

이 방식이 왜 효과적일까요? 루트 파일 (root file)의 가독성이 유지되며, 에이전트는 작업에 필요할 때만 세부 사항을 로드하기 때문입니다.

컨텍스트 (context)가 커질수록 이 점은 더욱 중요해집니다. 지침 파일이 모든 작업에 모든 워크플로우를 강제로 포함하게 만든다면 오히려 독이 될 수 있습니다. CSS 수정 작업에 사고 대응 매뉴얼이 필요하지는 않은 것과 같습니다.

에이전트에게 언제 말하고 언제 침묵해야 하는지 알려주세요

이 또한 간과해서는 안 될 중요한 부분입니다.

워크스페이스의 AGENTS.md에는 그룹 채팅 규칙이 있습니다. 이는 어시스턴트(assistant)에게 직접 언급되었을 때, 가치를 더할 수 있을 때, 또는 의미 있는 잘못된 정보를 바로잡아야 할 때 응답하도록 지시합니다. 또한 대화가 일상적이거나 이미 답변이 완료된 경우에는 침묵하도록 지시합니다.

이것 역시 리포지토리 (repo)와 관련이 있습니다. 에이전트에게도 커뮤니케이션 규범이 필요합니다.

개발 리포지토리의 경우 다음과 같을 수 있습니다:

## PR 코멘트 (PR comments)

- 변경 사항이 사용자가 관찰할 수 있는 동작에 영향을 미칠 때 코멘트를 남기세요.
...

에이전트는 기본적으로 많은 텍스트를 생성합니다. 여러분의 지침은 여러분의 프로젝트에서 '유용한 텍스트'가 어떤 모습인지 정의해야 합니다.

유지보수를 계약의 일부로 만드세요

워크스페이스 지침에는 단호한 규칙이 있습니다:

이 지침들을 업데이트하기

지속 가능한 저장소(repo) 규칙을 배우게 되면, 동일한 PR(Pull Request) 내에서 AGENTS.md 또는 관련 문서를 업데이트하세요. 특정 작업에 국한된 메모는 이 파일에 포함하지 마세요.

그런 다음 두 번째 문장을 강제하세요. 그렇지 않으면 AGENTS.md는 제목만 달린 채팅 기록(chat transcript)이 되어버릴 것입니다.

실용적인 구조

만약 제가 오늘 저장소 수준의 AGENTS.md를 시작한다면, 다음과 같은 형태를 사용할 것입니다:

# AGENTS.md

## 여기서 시작하세요
...

첫날에는 이 정도면 충분합니다. 이는 계속해서 반복(iterate)해 나감에 따라 그 위에 구축할 수 있는 프레임워크를 만들어 줍니다.

목표는 에이전트가 모든 것을 알게 만드는 것이 아닙니다. 목표는 첫 번째 움직임을 합리적으로 만들고, 위험한 움직임을 제한하며, 다음 파일이 무엇인지 명확하게 만드는 것입니다.

개방형 에이전트 생태계(agentic ecosystem)에서 공유된 관습(convention)은 유용하기 위해 반드시 무거울 필요는 없습니다. 어떤 에이전트라도 당신의 저장소에 도착했을 때 어디서부터 시작해야 할지 알 수 있을 만큼, 즉 AGENTS.md를 찾아낼 수 있을 만큼 충분히 예측 가능해야 합니다.