저는 계속해서 동일한 온보딩(onboarding) 질문으로 돌아오게 됩니다: 첫 10분 동안 어떤 일이 벌어지는가?

에이전트 도구(agent tools)의 경우, 그 시간대는 매우 가혹합니다. 개발자가 저장소(repo)를 열고, 에이전트를 시작하고, 변경 사항을 요청한 뒤, 도구가 프로젝트를 이해하는지 기다립니다. 만약 에이전트가 패키지 매니저(package manager)를 잘못 추측하거나, 테스트 경로(test path)를 놓치거나, 생성된 파일을 수정하거나, 개발자에게 저장소를 처음부터 다시 설명해 달라고 요청한다면, 신뢰도는 빠르게 떨어집니다.

그것이 매번 에이전트 모델(agent model)의 문제는 아닙니다. 상당 부분은 저장소 준비 상태(repo readiness)의 문제입니다.

Linux Foundation에서 호스팅하는 Agentic AI Foundation은 MCP, goose, AGENTS.md, agentgateway와 같은 프로젝트들을 위한 개방형 홈을 구축하고 있습니다. 그 작업은 거대하고 인프라적인 것처럼 들릴 수 있지만, 가장 유용한 진입점 중 하나는 작습니다: 첫 실행 시 에이전트가 저장소를 더 쉽게 이해할 수 있도록 만드는 것입니다.

AGENTS.md는 저장소 측의 컨텍스트(context)입니다. goose는 실질적인 런타임 경로(runtime path)입니다. 이 둘을 함께 사용하면 "에이전트가 여기저기 찔러보고 있는" 상태에서 "에이전트가 유용한 첫 번째 시도를 마친" 상태로 넘어갈 수 있는 방법을 제공합니다.

첫 번째 유용한 실행부터 시작하세요

"우리 에이전트 문서에 무엇을 적어야 할까?"라고 묻는 것부터 시작하지 마세요.

대신 이렇게 물으세요: 개발자가 이 저장소에서 10분 이내에 에이전트에게 무엇을 시킬 수 있어야 하는가?

한 가지 작업만 선택하세요. 시스템 전체가 아니라, 하나의 유용한 첫 번째 실행(first run)을 선택하세요.

예를 들어:

• 작은 버그를 위한 적절한 엔트리 포인트(entry point) 찾기
• 기존 함수 주변에 집중된 테스트 추가하기
• 근처에 알려진 소스 파일이 있는 문서 페이지 업데이트하기
• 특정 패키지나 모듈이 어떻게 연결되어 있는지 설명하기

그 첫 번째 실행이 여러분의 AGENTS.md에 역할을 부여합니다. 그것은 단순한 정책 나열(policy dump)이 아닙니다. 그것은 에이전트가 개발자의 첫 세션을 낭비하지 않기 위해 필요한 컨텍스트(context)입니다.

에이전트가 찾을 수 있는 곳에 저장소의 진실을 두세요

AGENTS.md는 코딩 에이전트 (coding agents)를 안내하기 위한 간단한 오픈 포맷이며, 프로젝트 사이트에 따르면 이미 6만 개 이상의 오픈 소스 프로젝트에서 사용되고 있습니다: https://agents.md.

이것이 작동하는 이유는 명확합니다. 에이전트에게는 저장소 지침 (repo instructions)을 위한 예측 가능한 장소가 필요하기 때문입니다. README 파일은 인간을 위해 작성됩니다. CI 파일은 자동화를 위해 작성됩니다. AGENTS.md는 보통 유지 관리자 (maintainer)의 머릿속에 들어 있는 세부 사항들을 에이전트에게 제공합니다.

여러분의 첫 번째 버전은 다음 질문에 답해야 합니다:

• 이 프로젝트는 어떤 종류인가?
• 소스 코드 (source code)는 어디에 있는가?
• 테스트 (tests)는 어디에 있는가?
• 에이전트가 편집을 피해야 할 파일은 무엇인가?
• 에이전트가 보존해야 할 스타일이나 아키텍처 (architecture) 선택 사항은 무엇인가?
• 에이전트가 작업이 완료되었다고 주장하기 전에 무엇을 해야 하는가?

누군가가 유지 관리할 수 있을 정도로 짧게 유지하세요. 오래된 에이전트 지침은 없는 것보다 더 나쁩니다. 왜냐하면 확신에 찬 실수를 유발하기 때문입니다.

유지 관리자 노트처럼 지침을 작성하세요

AGENTS.md 파일에는 브랜드 언어가 필요하지 않습니다. 유지 관리자 노트 (maintainer notes)가 필요합니다.

다음과 같이 작성하세요:

# AGENTS.md

## Project Shape
...

무엇이 빠져 있는지 주목하세요: 가짜 확신 (fake certainty)입니다.

현실적이지 않다면 "전체 테스트 스위트 (full test suite)를 실행하라"고 말하지 마세요. 확인하지 않은 명령어를 나열하지 마세요. 사용하지 않는 패키지 매니저 (package manager)를 사용하라고 에이전트에게 지시하지 마세요. 여러분의 에이전트 지침은 README만큼이나 진실되어야 합니다.

Goose 경로를 설계하세요

goose는 AAIF 산하의 오픈 소스 AI 에이전트 런타임 (runtime)입니다. 프로젝트 페이지에서는 이를 어떤 LLM으로든 설치, 실행, 편집 및 테스트를 수행할 수 있는 에이전트로 설명합니다: https://aaif.io/projects/goose.

온보딩 (onboarding)을 위해, goose를 여러분의 저장소 지침에 대해 테스트해 볼 수 있는 첫 실행 경로 (first-run path)라고 생각하세요.

좋은 첫 실행 경로는 세 가지 요소를 갖추고 있습니다:

• 명확한 시작 작업
• 저장소 수준의 AGENTS.md
• 눈에 보이는 종료 지점

종료 지점(stopping point)이 중요합니다. 에이전트가 코드를 변경한다면, 개발자는 그것이 올바른 작업을 수행했는지 어떻게 알 수 있을까요? 에이전트가 자신이 변경한 파일들을 가리켜야 할 수도 있습니다. 실행할 테스트에 대해 설명해야 할 수도 있습니다. 혹은 마이그레이션(migration), 생성된 파일(generated file), 또는 공개 API(public API)를 건드리기 전에 멈춰야 할 수도 있습니다.

이러한 내용은 AGENTS.md에 포함되어야 합니다.

에이전트가 더 나은 질문을 하도록 만들기

유용한 에이전트는 모든 것을 알 필요는 없습니다. 추측을 멈춰야 할 때를 알아야 합니다.

불확실성에 대한 가이드를 추가하세요:

## 불확실할 때 (When Unsure)

요청된 변경 사항이 인증(auth), 결제(billing), 데이터 삭제(data deletion) 또는 운영 환경 설정(production configuration)을 건드리는 경우, 편집하기 전에 질문하십시오.
...

이것이 왜 도움이 될까요? 첫 실행 이탈(first-run drop-off)은 종종 '의외성(surprise)'에서 발생하기 때문입니다. 에이전트가 잘못된 레이어(layer)를 편집하거나, 광범위한 리팩터링(refactor) 경로를 택하거나, 위험한 영역을 일반적인 코드처럼 취급할 때 발생합니다.

좋은 지침은 폭발 반경(blast radius)을 좁혀줍니다.

문서를 제품의 표면(Product Surface)으로 취급하기

개발자 온보딩(onboarding)은 제품과 별개의 것이 아닙니다. 문서는 사용자가 무엇을 시도할지, 어디에서 막힐지, 그리고 다시 돌아올지 여부를 결정합니다.

에이전트 준비가 된 저장소(agent-ready repos)에서 AGENTS.md는 그 제품 표면의 일부입니다. 따라서 퀵스타트(quickstart)를 검토하는 것과 동일한 방식으로 이를 검토하십시오:

• 첫 번째 작업이 명확한가?
• 저장소의 경계(repo boundaries)가 명시되어 있는가?
• 설정 가정(setup assumptions)이 최신 상태인가?
• 위험한 영역이 명시되어 있는가?
• 새로운 기여자가 무엇이 "완료(done)"인지 알 수 있는가?

이 지점이 바로 AAIF의 개방형 생태계 관점이 실용적으로 변하는 지점입니다. 에이전트 도구가 여러 프로젝트에 걸쳐 작동하려면, 유지 관리자들은 특정 벤더, 특정 에디터, 또는 특정 모델에 의존하지 않는 공유된 컨벤션(conventions)이 필요합니다. AGENTS.md는 저장소에 이식 가능한 지침 레이어(instruction layer)를 제공합니다. goose는 개발자에게 이를 대상으로 에이전트 워크플로우(agent workflows)를 실행할 수 있는 개방적인 방법을 제공합니다.

작은 파일이지만, 강력한 영향력을 가집니다.

실무 체크리스트

에이전트를 저장소에 투입하기 전에 다음을 사용하세요:

1. 새로운 개발자가 가치 있게 여길 만한 첫 실행 작업(first-run task)을 하나 선택합니다.
2. 프로젝트의 형태(project shape), 테스트 기대치(test expectations), 그리고 피해야 할 파일들을 포함하여 AGENTS.md를 추가하거나 업데이트합니다.
3. 직접 검증하지 않은 명령어는 제거합니다.
4. 에이전트에게 위험한 코드 경로(risky code paths) 주변에서 어떻게 행동해야 하는지 알려줍니다.
5. goose 또는 선택한 에이전트 런타임(agent runtime)을 통해 첫 번째 작업을 실행합니다.
6. 에이전트가 잘못 추측한 부분을 바탕으로 AGENTS.md를 수정합니다.
7. 첫 번째 실행 결과가 진지하게 검토할 만한 수준이 될 때까지 이 과정을 반복합니다.

목표는 에이전트를 완벽하게 만드는 것이 아닙니다. 목표는 첫 세션(first session)을 읽을 수 있게(legible) 만드는 것입니다.

개발자는 저장소(repo)를 열고, 에이전트를 시작하고, 범위가 지정된 하나의 작업(scoped task)을 요청한 뒤, 스스로 저장소 가이드(repo tour guide)가 되지 않고도 그 결과를 이해할 수 있어야 합니다.