교육 문의커뮤니티 입장하기

AGENTS.md와 CLAUDE.md 뜻과 작성법: intent.md와 하네스까지

AGENTS.md는 코딩 에이전트가 프로젝트에서 일할 때 읽는 지침 파일로, 공식 사이트는 "에이전트를 위한 README"라고 부릅니다. 클로드 코드는 같은 역할의 CLAUDE.md를 읽고, 폴더마다 둔 지침 파일은 넓은 범위부터 좁은 범위 순으로 이어 붙여 읽습니다. 지침 파일은 일하는 방식을 알려 주는 글일 뿐 권한을 막는 장치는 아니며, 일감마다 왜 하는지를 적는 intent.md와 검사, 권한까지 묶은 하네스와 함께 씁니다.

같은 말:AGENTS.mdCLAUDE.mdagent.md 작성법agents.md claude.md 차이에이전트 지침 파일intent.md하네스 엔지니어링harness engineeringharness 뜻

게시 수정 코스 2 / 5번째 개념
지금까지 100명 넘게 읽었어요, 69%가 끝까지 읽었어요
#AI#바이브코딩#자동화
Share
준이아빠AI가 일하는 법AI 친구들의 작업실 구경하기 ↗
목차
  1. AGENTS.md란 무엇인가요?
  2. AGENTS.md와 CLAUDE.md는 무엇이 다른가요?
  3. 폴더 여러 곳에 두면 어떻게 읽나요?
  4. AGENTS.md 작성법: 무엇을 적나요?
  5. 지침 파일로 막을 수 없는 것은 무엇인가요?
  6. intent.md란 무엇인가요?
  7. 하네스 엔지니어링이란 무엇인가요?
  8. 📚 참고 자료

AGENTS.md는 코딩 에이전트가 프로젝트에서 일할 때 읽는 지침 파일입니다. 공식 사이트 agents.md는 이 파일을 "에이전트를 위한 README"라고 부르고, 빌드 명령, 코드 규칙, 테스트 방법처럼 사람용 README에는 잘 안 적는 내용을 담는 곳이라고 설명합니다. 클로드 코드는 같은 역할을 하는 CLAUDE.md를 읽습니다. 이 글은 여러 폴더의 지침이 어떻게 겹쳐 읽히는지, 도구마다 어떤 파일을 읽는지, 지침으로 막을 수 없는 것은 무엇인지 보고, 일감 단위의 intent.md와 하네스 엔지니어링까지 다룹니다.

AI 에이전트 개념

AGENTS.md,
겹쳐 읽는 지침 필름

에이전트는 시작한 폴더에서 위쪽 폴더까지 지침 파일을 찾아 겹쳐 읽습니다.
packages/web 폴더에서 에이전트를 시작해 보세요.

예시 프로젝트 폴더

  • ~/.claude/CLAUDE.md내 컴퓨터 전체(사용자 지침)
  • shop/
  • CLAUDE.md저장소 공통
  • packages/
  • web/
  • CLAUDE.md웹 화면 코드에만

지침 필름 세 장(아직 겹치기 전)

1 사용자 지침~/.claude/CLAUDE.md

답은 한국어로. 커밋 메시지도 한국어로.

2 저장소 지침shop/CLAUDE.md

테스트는 npm test로 돌린다. 운영 설정 파일은 고치지 않는다.

3 하위 폴더 지침shop/packages/web/CLAUDE.md

화면 글자는 모두 번역 파일에서 가져온다. 들여쓰기는 2칸.

지침 파일은 에이전트에게 주는 일하는 방식 안내서입니다.
어디에 두느냐가 누구에게 적용되는지를 정합니다.

도구마다 읽는 파일이 다릅니다

도구를 바꿔 보세요. 같은 폴더에서 그 도구가 읽는 파일이 켜집니다.

  • shop/
  • AGENTS.md
  • AGENTS.override.md
  • CLAUDE.md
  • GEMINI.md
  • .cursor/rules/
  • .github/copilot-instructions.md

CLAUDE.md를 읽고, v2.1.277부터는 AGENTS.md도 직접 읽습니다.

  • 기본값으로는 작업 폴더와 위쪽 폴더에 CLAUDE.md나 CLAUDE.local.md가 없을 때만 AGENTS.md를 읽습니다.
  • 사용자, 프로젝트, 로컬, 조직 정책 네 범위가 있고 넓은 범위부터 이어 붙입니다.
  • AGENTS.override.md와 .agents 폴더 안의 파일은 읽지 않습니다.

여러 도구를 함께 쓴다면, CLAUDE.md 한 줄로 AGENTS.md를 가져오기

@AGENTS.md

내용은 AGENTS.md 한 곳에 두고, CLAUDE.md에는 가져오기 한 줄만 둡니다. 클로드 코드 문서는 윈도에서도 함께 일한다면 심볼릭 링크보다 이 방식을 권합니다.

2026년 10월 22일 각 도구 공식 문서 기준입니다. 지원 범위는 버전마다 바뀌므로 쓰는 도구의 문서에서 다시 확인합니다.

지침은 안내일 뿐, 막는 것은 권한입니다

에이전트가 위험한 명령을 실행하려 합니다.
막는 방법을 바꿔 보세요.

에이전트가 실행하려는 명령(예시)운영 데이터베이스의 표 하나를 지우는 명령

실행됩니다

아무 안내도 제한도 없어 에이전트가 판단한 대로 실행합니다.

"CLAUDE.md content is delivered as a user message after the system prompt", it is "context, not enforced configuration."

CLAUDE.md는 시스템 프롬프트 뒤의 사용자 메시지로 전달되며, 강제되는 설정이 아니라 맥락입니다.

Claude Code docs, Memory

권한 모드와 설정은 클로드 코드 권한 수업에서 다룹니다. 명령은 재현하지 않도록 뜻만 적었습니다.

intent.md, 지침 파일, 하네스는 맡은 층이 다릅니다

층을 눌러 펼쳐 보세요. 위에서 아래로 갈수록 범위가 넓어집니다.

intent.md는 업계 표준 파일이 아니라 플레이북이 제안한 조직용 양식이며, 다른 도구가 자동으로 읽는다는 근거는 없습니다.

정리

  1. 1

    AGENTS.md는 에이전트를 위한 README입니다. 클로드 코드는 CLAUDE.md를 읽고, 폴더마다 둔 지침은 넓은 범위부터 이어 붙여 읽습니다.

  2. 2

    지침은 맥락일 뿐 권한 장치가 아닙니다. 꼭 막을 일은 권한 설정으로 막고, 지침은 확인할 수 있는 문장으로 짧게 씁니다.

  3. 3

    intent.md는 일감마다 무엇을 왜 하는지, 지침 파일은 어떻게 일하는지를 적고, 하네스는 모델을 뺀 지침과 검사와 권한 전부를 뜻합니다.

다음 수업 클로드(Claude) 이해하기 →

AGENTS.md란 무엇인가요?

AGENTS.md는 코딩 에이전트에게 프로젝트의 작업 방식을 알려 주는 마크다운 파일입니다. agents.md 공식 사이트는 이 파일을 "에이전트를 위한 README"라고 부르며, 에이전트가 늘 같은 곳에서 빌드 방법, 테스트 방법, 코드 규칙을 찾을 수 있게 하는 자리라고 설명합니다. 정해진 필수 항목은 없고 보통의 마크다운으로 씁니다.

AGENTS.md는 2025년 8월에 나왔습니다. 리눅스 재단과 오픈AI는 오픈AI가 공개했다고 쓰고, agents.md 사이트는 오픈AI Codex, Amp, 구글 Jules, Cursor, Factory의 공동 노력에서 나왔다고 씁니다. 2025년 12월 9일에는 리눅스 재단 산하 Agentic AI Foundation으로 옮겨졌고, 당시 6만 개가 넘는 오픈소스 프로젝트와 에이전트 프레임워크가 쓰고 있다고 발표됐습니다. 집계 방법은 공개되지 않았습니다.

AGENTS.md와 CLAUDE.md는 무엇이 다른가요?

하는 일은 같고, 읽는 도구가 다릅니다. CLAUDE.md는 클로드 코드가 읽는 지침 파일이고, AGENTS.md는 Codex, Cursor, Gemini CLI 등 여러 도구가 함께 쓰려고 만든 이름입니다. 클로드 코드는 v2.1.277부터 AGENTS.md도 직접 읽지만, 기본값으로는 작업 폴더와 위쪽 폴더에 CLAUDE.md나 CLAUDE.local.md가 없을 때만 읽습니다.

도구기본으로 읽는 파일AGENTS.md
클로드 코드CLAUDE.md, CLAUDE.local.mdv2.1.277부터 읽음(CLAUDE.md가 없을 때 기본)
CodexAGENTS.md(폴더마다 AGENTS.override.md 우선)기본 파일
Gemini CLIGEMINI.md설정에 넣으면 읽음
Cursor.cursor/rules루트와 하위 폴더 지원
GitHub Copilot.github/copilot-instructions.md기능마다 지원 범위가 다름

여러 도구를 함께 쓴다면 내용은 AGENTS.md 한 곳에 두고, CLAUDE.md에는 @AGENTS.md 한 줄을 적어 가져오는 방법이 있습니다. 클로드 코드 문서는 윈도 사용자가 있으면 심볼릭 링크보다 이 가져오기 방식을 권합니다.

폴더 여러 곳에 두면 어떻게 읽나요?

넓은 범위부터 좁은 범위 순으로 모두 이어 붙여 읽습니다. 클로드 코드는 조직 정책, 사용자(~/.claude/CLAUDE.md), 프로젝트, 로컬 순으로 읽고, 작업 폴더와 그 위의 모든 폴더에서 CLAUDE.md를 찾습니다. 문서는 찾은 파일들이 서로 덮어쓰지 않고 이어 붙으며, 시작한 폴더에 가까운 지침이 나중에 읽힌다고 씁니다. 하위 폴더의 CLAUDE.md는 처음에 읽지 않고, 클로드가 그 폴더의 파일을 다룰 때 불러옵니다.

Codex도 전역 폴더(~/.codex)를 먼저 보고 저장소 루트부터 현재 폴더까지 폴더마다 파일 하나씩 이어 붙이며, 합친 크기의 기본 한도는 32KiB입니다. agents.md 사이트는 편집하는 파일에 가장 가까운 AGENTS.md가 우선하고, 사용자가 채팅으로 준 지시가 모든 것보다 우선한다고 씁니다. 두 지침이 부딪히면 클로드가 임의로 하나를 고를 수 있다고 클로드 코드 문서가 적고 있으므로, 서로 다른 말을 하는 줄은 정리해 둡니다.

AGENTS.md 작성법: 무엇을 적나요?

에이전트가 매번 알아야 하는데 코드만 봐서는 알기 어려운 것을 적습니다. agents.md 사이트가 자주 쓰는 항목으로 드는 것은 프로젝트 개요, 빌드와 테스트 명령, 코드 스타일, 테스트 방법, 보안 주의 사항 같은 것들입니다.

# 프로젝트 온라인 쇼핑몰. 화면은 packages/web, 서버는 packages/api. # 명령 - 설치: npm install - 테스트: npm test (커밋 전에 반드시 통과) # 규칙 - 들여쓰기는 2칸 - 화면 글자는 번역 파일(locales/)에서 가져온다 # 건드리지 않는 것 - 운영 설정 파일(config/production)

클로드 코드 문서가 권하는 기준은 세 가지입니다. 첫째, 확인할 수 있게 씁니다. "코드를 잘 정리"보다 "들여쓰기 2칸"이 낫습니다. 둘째, 짧게 씁니다. 파일당 200줄 아래를 권하며, 길수록 맥락을 더 쓰고 지키는 정도가 떨어진다고 씁니다. 셋째, 같은 실수를 두 번 하거나 같은 교정을 또 입력하게 될 때 한 줄을 더합니다. 여러 단계 절차나 일부 코드에만 해당하는 내용은 지침 파일보다 스킬이나 경로별 규칙이 맞습니다. 클로드 코드에서는 /init으로 초안을 만들고 /memory로 고칠 수 있습니다.

지침 파일이 많을수록 좋은 것은 아닙니다. 2026년 2월에 나온 한 연구(arXiv 2602.11988)는 저장소의 지침 파일이 작업 성공률을 대체로 높이지 않았고 추론 비용은 20% 넘게 늘었다고 보고했습니다. 꼭 필요한 줄만 남기는 편이 낫다고 생각하는 편이에요.

지침 파일로 막을 수 없는 것은 무엇인가요?

지침 파일은 권한 장치가 아닙니다. 클로드 코드 문서는 CLAUDE.md가 시스템 프롬프트 뒤의 사용자 메시지로 전달되는 맥락일 뿐 강제되는 설정이 아니라고 쓰고, Cursor 문서도 AI 지침을 유일한 보안 장치로 쓰지 말라고 합니다. 에이전트는 지침을 대개 따르지만, 지침이 길거나 서로 부딪히거나, 읽어 들인 자료 속 다른 지시에 밀리면 지키지 않을 수 있습니다. 자료 속 지시가 끼어드는 문제는 프롬프트 인젝션에서 다뤘습니다.

반드시 막을 파일 접근이나 명령은 권한 설정, 샌드박스, 승인 절차로 막습니다. 클로드 코드의 권한 모드는 클로드 코드 권한 모드에서 다룹니다. 비밀번호나 키 같은 비밀값도 지침 파일에 적지 않습니다. 지침 파일은 저장소에 함께 올라가 다른 사람과 도구가 읽는 글입니다.

intent.md란 무엇인가요?

intent.md는 일감 하나를 시작할 때 무엇을, 왜, 어떤 제약 아래 하는지 적는 문서입니다. 앤트로픽이 2026년 8월 21일 claude.com 블로그에 공개한 "AI 네이티브 개발 플레이북(The AI-native SDLC playbook)"의 첫 단계(Plan) 문서로 소개됐습니다. 아이디어가 생기면 클로드와 함께 범위, 사용자, 제약, 성공 기준을 묻고 답하며 정리하고, 제품 책임자가 검토해 고친 뒤 저장소에 올립니다.

항목적는 내용
문제(Problem)지금 무엇이 불편한지
기대 결과(Proposed outcome)끝나면 무엇이 달라지는지
영향받는 사용자와 시스템누가, 어떤 시스템이 바뀌는지
제약(Constraints)지켜야 할 규정, 기한, 기술 조건
열린 질문(Open questions)아직 정하지 못한 것

승인된 intent.md가 다음 단계인 설계 문서(spec.md)와 계획(plan.md)으로 이어지고, 이 커밋들이 누가 무엇을 요청하고 승인했는지 남기는 기록이 됩니다. 정리하면 AGENTS.md나 CLAUDE.md는 프로젝트에서 늘 같은 "어떻게"를, intent.md는 일감마다 바뀌는 "왜"를 적습니다. 다만 intent.md는 업계 표준 파일이 아니라 플레이북이 제안한 조직용 양식이고, 다른 도구가 자동으로 읽는다는 근거는 없습니다.

하네스 엔지니어링이란 무엇인가요?

하네스 엔지니어링은 AI 에이전트에서 모델을 뺀 나머지, 즉 지침, 도구, 검사, 권한을 설계하는 일입니다. 영어 harness는 케임브리지 사전 기준으로 말에 채우는 마구, 동사로는 힘을 다스려 쓴다는 뜻입니다. Thoughtworks의 Birgitta Böckeler는 2026년 4월 2일 글에서 하네스를 AI 에이전트에서 모델을 뺀 모든 것이라고 정의하고 "에이전트 = 모델 + 하네스"라고 썼습니다.

그는 하네스를 두 종류로 나눕니다. 가이드는 에이전트가 행동하기 전에 방향을 잡는 것으로, AGENTS.md 같은 지침 파일과 스킬이 여기에 듭니다. 센서는 행동한 뒤 스스로 고치게 돕는 것으로, 테스트, 린터, 타입 검사, 리뷰 에이전트가 듭니다. 같은 문제가 여러 번 생기면 가이드와 센서를 고치라는 것이 그의 권고입니다.

오픈AI도 "Harness engineering" 글에서 사람이 직접 쓴 코드 없이 Codex로 약 100만 줄 규모의 내부 제품을 만든 경험을 소개하며, 엔지니어 세 명이 약 1,500건의 변경 요청을 병합했다고 밝혔습니다. 에이전트가 무엇인지는 AI 에이전트에서 다룹니다.

📚 참고 자료

2026년 10월 22일 위 공식 문서와 글에서 파일 이름, 읽는 순서, 정의를 확인했습니다. 폴더 구조와 지침 문장은 이 글의 학습용 가상 예제입니다.

Share

제대로 이해했는지 한 문제로 확인해 볼까요?

답을 고르면 바로 풀이가 나와요.

저장소 루트의 CLAUDE.md에는 "들여쓰기 4칸", packages/web/CLAUDE.md에는 "들여쓰기 2칸"이 적혀 있습니다. packages/web에서 클로드 코드를 시작하면 어떻게 읽나요?

예제나 확인 질문을 직접 시도한 뒤 완료 표시해요. 더 연습할 내용이 남으면 표시하지 않고 다음 글을 읽어도 됩니다. 완료 버튼은 이해도를 채점하지 않으며 잘못 표시하면 취소할 수 있어요.

3개념 / 클래스멀티 에이전트 오케스트레이션(Multi-Agent Orchestration) 뜻과 설계

이어서 배우면 좋은 개념

관련 글