제가 계속해서 마주치는 실패 사례는 다음과 같습니다.

한 팀이 코딩 에이전트(coding agent)에게 저장소(repo), 작업(task), 그리고 아마도 README를 제공합니다. 에이전트는 파일을 찾고 코드를 작성할 수 있지만, 여전히 운영 규칙을 추측해야 합니다.

패키지 매니저(package manager)를 추측합니다.

어떤 체크(checks)가 중요한지 추측합니다.

생성된 파일(generated files)을 편집해도 안전한지 추측합니다.

"완료(done)\

마법이 아닙니다. 그저 지루한 부분을 잊어버릴 확률을 줄여주는 것뿐입니다.

기술(Skills)의 역할

AGENTS.md가 실제로 제 역할을 하기 시작하면, 저는 한 가지 레이어를 더 추가하겠습니다: 바로 기술(skills)입니다.

이 파일이 모든 반복되는 워크플로우(workflow)를 붙여넣는 장소가 되어서는 안 됩니다. 그렇게 되면 잡동사니 서랍(junk drawer)으로 변질되기 때문입니다.

더 깔끔한 구분 방식은 다음과 같습니다:

• AGENTS.md는 상시 적용되는 규칙(standing rules)을 명시합니다.
• 기술(Skills)은 반복 가능한 작업 루틴(task routines)을 설명합니다.
• MCP와 확장 기능(extensions)은 에이전트에게 도구(tools)와 데이터에 대한 접근 권한을 부여합니다.

이는 Goose에도 깔끔하게 매핑됩니다. Goose에는 선택적인 지원 파일과 함께 재사용 가능한 지침 세트(instruction sets)를 위한 Skills Marketplace가 있습니다.

백엔드 서비스의 경우, AGENTS.md는 마이그레이션(migrations), API 변경, 릴리스(releases)를 별도의 기술(skills)로 라우팅(route)할 수 있습니다.

이렇게 하면 AGENTS.md 파일은 짧게 유지되면서도, 작업 루틴은 다른 곳에서 필요한 만큼 상세하게 작성될 수 있습니다.

구분 방법은 간단합니다: 만약 해당 규칙이 저장소(repo) 내의 거의 모든 작업에 적용되어야 한다면 AGENTS.md에 넣으세요. 만약 특정 종류의 작업을 위한 반복 가능한 루틴이라면, 그것을 기술(skill)로 만들고 AGENTS.md에서 그 기술로 라우팅하세요.

시도해 볼 만한 작은 워크플로우

이미 에이전트를 사용 중인 리스크가 낮은 저장소 하나를 골라 다음을 시도해 보세요.

다섯 가지 섹션이 포함된 AGENTS.md 파일을 추가합니다:

1. Setup (설정): 권장되는 설치 및 실행 명령.
2. Checks (체크): 가장 작고 신뢰할 수 있는 테스트, 린트(lint), 또는 타입 체크(typecheck) 명령.
3. Boundaries (경계): 에이전트가 건드려서는 안 되는 파일, 데이터 또는 작업.
4. Done criteria (완료 기준): 에이전트가 작업을 멈추기 전에 제공해야 하는 증거.
5. Skills (기술): 에이전트가 추측하는 대신 사용해야 할 작업별 루틴.

그런 다음 동일한 작업을 두 번 시도해 보세요:

작업: 새로운 설정 플래그(config flag)에 대한 예시를 추가하세요.

먼저 AGENTS.md 없이 수행해 보고, 당신이 무엇을 설명해야 하는지 관찰하세요.

그다음 파일을 추가하고 다시 요청해 보세요.

유용한 테스트 항목:

• 에이전트가 올바른 체크(checks)를 수행했는가?
• 생성된 파일(generated files)을 피했는가?
• 당신의 프롬프트(prompt)가 더 짧아졌는가?

만약 대답이 '아니오'라면, 해당 파일은 아마도 너무 모호하거나, 너무 길거나, 혹은 에이전트(agent)가 실행할 수 없는 지침들로 가득 차 있을 것입니다.

좋은 첫 번째 AGENTS.md

여기서부터 시작하세요:

# AGENTS.md

## 프로젝트 맵 (Project Map)
...

이 정도면 유용하기에 충분합니다. 또한 누군가가 유지 관리할 수 있을 만큼 충분히 짧습니다.

아키텍처 에세이(architecture essays), 지향하는 가치(aspirational values), 저장소(repo) 내의 모든 명령어, 그리고 프롬프트 트랜스크립트(prompt transcript)에 포함되기를 원치 않는 개인적인 컨텍스트(private context)는 피하세요. 만약 그 지침이 에이전트(agent)의 동작을 변화시키지 않는다면, 삭제하세요.

핵심 요약 (The Takeaway)

AGENTS.md는 마법 같은 안전 계층(safety layer)이 아닙니다.

그것은 당신이 이미 반복하고 있었던 지침들, 즉 설정(setup), 체크(checks), 경계(boundaries), 그리고 완료(done)의 의미를 담아두는 간단한 장소입니다.

저에게 있어 실질적인 기준은 이것입니다: 에이전트(agent)가 더 적은 프롬프트(prompting)만으로도 작은 작업을 수행할 수 있고, 여전히 실행한 체크(checks)를 보여줄 수 있는가?

만약 그렇다면, 저장소(repo)의 모호함이 줄어든 것입니다.

만약 아니라면, 해당 파일은 더 많은 작업이 필요합니다.