Agentic Coding 시대의 Repo 부트스트래핑 가이드 Part 1: AGENTS.md 와 spec 문서 지형도

Thu, 28 May 2026 19:02:00 +0900

이 글은 Claude Opus 4.7 을 이용해 초안이 작성되었으며, 이후 퇴고를 거쳤습니다.

들어가며: README 한 장으로 안 되는 시대

신규 서비스를 위한 git repo 를 막 만들었다고 합시다. 2년 전이라면 README.md 한 장에 빌드 명령과 디렉터리 구조를 적고, 나머지는 코드와 머릿속에서 합의된 관행으로 굴러갔습니다. 새 팀원이 들어오면 옆 자리 동료가 30분쯤 설명해 주고, 그걸로 충분했습니다.

지금은 그 “옆 자리 동료” 역할의 절반 이상을 Claude Code, Codex CLI, Gemini CLI, Cursor 같은 에이전트가 맡고 있습니다. 그런데 에이전트는 옆 자리에 앉지 않습니다. 매 세션마다 처음 합류한 신입처럼 repo 에 들어와서, 우리가 적어 둔 텍스트만 읽고 일을 시작합니다. 에이전트에게 “이 프로젝트는 이런 곳이고, 이런 규칙으로 일한다” 를 전달하는 문서가 부실하면, 에이전트가 만드는 결과물의 품질은 운에 좌우됩니다.

Codex on philipjkim

Agentic Coding 시대의 Repo 부트스트래핑 가이드 Part 1: AGENTS.md 와 spec 문서 지형도

들어가며: README 한 장으로 안 되는 시대