AGENTS.md 예시와 하네스 실습, 지시 파일 있는 코덱스 비교

같은 웹서비스를 Codex에게 두 번 만들게 하되, 한쪽에는 AGENTS.md·PLANS.md·스킬⁠·평가 샘플 같은 지시 파일을 갖춰 주고 다른 쪽에는 프롬프트 한 줄만 준 실습을 정리했습니다. 실습 저장소에 실제로 들어 있는 AGENTS.md 예시와 채점표, 결과가 갈린 이유, 내 프로젝트에 같은 장치를 심는 순서까지 담았습니다.

화면은 그럴듯한데 쓸 수 없는 결과물

AI로 화면 하나, 기능 하나를 만드는 일은 놀랄 만큼 빨라졌습니다. 그런데 결과물을 열어 보면 겉모습만 그럴듯하고 안쪽 로직은 비어 있는 경우가 많습니다. 실제로 운영할 서비스로 이어지지 못하는 이유입니다.

하네스(harness)는 말에 채우는 마구, 강아지 산책 줄처럼 힘센 대상을 원하는 방향으로 이끄는 장치를 말합니다. 지금의 LLM은 10년 넘게 코드를 짠 사람처럼 빠르게 코드를 쓰지만, 문제를 날카롭게 정의하고 기획하고 테스트해서 실제 서비스로 만드는 능력은 아직 부족합니다. 너무 잘 달리는데 길들지 않아서, 주인이 원하는 길이 아니라 제 눈에 그럴듯한 방향으로 질주합니다. 하네스 엔지니어링은 이 질주를 통제하는 일입니다.

프롬프트에서 컨텍스트, 그리고 하네스로

이 흐름은 세 단계로 볼 수 있습니다.

• 프롬프트 엔지니어링: 모델이 충분히 똑똑하지 않던 시기. 원하는 답을 어떻게 끌어낼지 고민했다
• 컨텍스트 엔지니어링: 모델에게 필요한 정보를 어떻게 잘 전달할지 고민했다
• 하네스 엔지니어링: 모델이 좋아지고 쥐여 준 도구도 많아지자 중구난방으로 움직인다. 이걸 어떻게 통제할지가 과제가 됐다

이런 장치가 효과가 있는지 잰 연구도 있습니다. 2026년 2월 arXiv에 공개된 SkillsBench는 사람이 다듬은 스킬(작업 절차를 적은 지시 파일 묶음)을 붙였을 때와 안 붙였을 때를 같은 과제로 비교했습니다. 처음 공개된 판에서는 7가지 에이전트⁠·모델 조합에서 과제 통과율이 평균 16.2%포인트 올랐고, Codex CLI와 GPT-5.2 조합은 30.6%에서 44.7%로 14.1%포인트 올랐습니다. 다만 같은 연구에서 AI가 스스로 만든 스킬은 평균적으로 도움이 되지 않았고, 분야에 따라 효과 차이가 컸습니다.

이미 쓰고 있던 하네스

하네스라는 말은 2026년에 퍼졌지만, Codex나 Claude Code를 써 본 사람은 이미 하네스를 쓰고 있었습니다. 권한(퍼미션) 설정, 메모리 기능, AI가 특정 폴더 안에서만 작업하게 하는 설정이 모두 하네스의 일종입니다. 하네스로 묶을 수 있는 것은 이렇습니다.

• 환경 제약: 모델이 어디까지 쓰고 어디까지 실행할 수 있는지 정하기
• 작업 구조: 계획을 어떻게 세우고 어떤 역할과 일을 줄지 기획해서 전달하기
• 검증 설계: 만든 코드를 어떻게 테스트하고 평가할지 지시하기
• 기록 지시: 모델이 한 일을 문서로 남기게 하기
• 멀티 에이전트 분담: 데이터 수집, 프런트엔드, 백엔드, 마지막 평가 에이전트처럼 임무와 순서를 나눠 주기

오해 하나는 짚어 둡니다. 하네스 엔지니어링은 프롬프트를 길게 쓰는 일이 아닙니다. 구조를 짜서 탄탄하게 설계한 뒤 전달하는 전략입니다.

AI를 위한 README, 지시 파일 4종

개발자가 README에 실행 방법을 적어 두듯, 에이전트가 읽을 마크다운 지시서를 폴더마다 만들어 두면 에이전트는 그 문서를 바탕으로 일합니다. 파일 이름을 정해진 대로 지으면 에이전트가 알아서 찾아 읽습니다.

AGENTS.md: 항상 지킬 규칙

에이전트가 언제나 지켜야 하는 기본 운영 규칙을 적는 파일입니다. Codex는 프로젝트 맨 위 폴더의 AGENTS.md를 전역 규칙으로 읽고, 하위 폴더에 AGENTS.md가 또 있으면 그 폴더에서 작업할 때 그 규칙을 더해 읽습니다. 예를 들어 프런트엔드 폴더 안에 AGENTS.md를 따로 두면, 그 폴더 작업에만 적용되는 규칙을 자동으로 전달할 수 있습니다.

PLANS.md: 이번 작업의 실행 계획서

이번 작업에서 무엇을 어떤 순서로 할지, 위험 요소는 무엇인지 담는 계획서입니다. AGENTS.md가 늘 적용되는 규칙이라면, PLANS.md는 작업 하나에 딸린 계획입니다.

skills 폴더: 반복 절차를 따로

매번 반복해서 알려 줘야 하는 절차는 스킬 파일(SKILL.md)로 떼어 둡니다. Codex는 프로젝트의 .agents/skills 폴더에서 스킬을 읽습니다. 스킬 파일 맨 위에 언제 쓰는 스킬인지 설명을 적어 두면, 에이전트가 그 작업을 할 때 알아서 꺼내 씁니다.

평가 샘플과 체크리스트: 스스로 채점하게

AI가 만든 결과를 스스로 평가하게 하는 장치입니다. 평가용 폴더(실습 저장소의 evals)에 정답 형태의 대표 데이터를 넣어 두면, AI가 만든 결과를 그것과 비교해 품질을 확인할 수 있습니다. 체크리스트 파일을 두면 AI가 결과물을 하나씩 확인하며 놓친 부분과 남은 일을 기록합니다.

실습 저장소 AGENTS.md 예시

실습 저장소는 깃허브 jaypakdevkr/harness_eng입니다. 안에 폴더가 두 개 있습니다.

• harness_eng_with: AGENTS.md, PLAN.md, evals/eval_samples.json, skills 폴더(source-intake, ui-polish-check, qa-deadline-links, release-readiness 네 가지)
• harness_eng_without: 프롬프트 한 줄만 적힌 README.md

만들 서비스는 대한민국의 AI 관련 정부 지원 사업, 공모전, 해커톤, 연구과제 공고를 한눈에 보여 주는 웹사이트입니다.

AGENTS.md에 적힌 것

AGENTS.md는 "무엇을 만들라"보다 "어떻게 일하고 언제 끝났다고 볼지"에 공을 들였습니다. 내용을 줄이면 이렇습니다.

• 제품 목표: 대상(학생⁠·스타트업⁠·기업⁠·연구자)별 필터, 마감 임박 공고 확인
• 꼭 지킬 규칙: 카드마다 공고명⁠·기관⁠·대상⁠·마감일⁠·링크 표시, 마감된 공고 숨김, 중복 제거, "오늘 마감"과 "이번 주 마감" 표시, 빈 화면⁠·로딩⁠·오류 상태 구현
• 기술 규칙: 작게 나눠 구현, 단계마다 실행 가능한 상태 유지, 변경 뒤 lint·test·build 먼저 실행, 스크립트로 확인할 수 있는 건 스크립트로 확인
• 데이터 품질 규칙: 날짜는 YYYY-MM-DD로 통일, 기관+공고명+마감일이 같으면 중복 후보, 필수 칸이 비면 무효 처리
• 완료 조건: 데이터 소스 3개 이상 연결, 검색⁠·필터⁠·정렬 동작, 링크 유효성 검사 통과, README에 실행법 기재

PLAN.md에는 마일스톤 6개(표준 스키마 정의, 소스 3개 파서, 카드 목록, 검색⁠·필터⁠·정렬, QA 스크립트, README)와 위험 요소(사이트마다 다른 날짜 형식, 단순 문자열 비교로는 부족한 중복 판정, 상대 경로 링크)가 적혀 있습니다. 데이터 수집 스킬(source-intake)에는 공고 데이터의 표준 칸(기관, 공고명, 분류, 대상, 시작일, 마감일, 링크 등)과 정규화 절차가 있어서, 에이전트가 데이터를 마구 모으지 않고 이 형태에 맞춰 수집하게 됩니다.

비교용 폴더의 프롬프트

지시 파일이 없는 쪽에는 이 두 줄만 있습니다.

대한민국 AI 관련 정부 지원 사업과 공모전을 한눈에 보여주는 웹서비스를 만들어줘. 검색, 필터, 카드 UI를 포함해.

비교 실습 따라 하기

준비물

• 웹 브라우저(실습 저장소 열기)
• Codex(웹서비스 만들기). Codex 앱이나 Codex CLI
• Claude Code(평가하기)
• Git(저장소 내려받기)

1. 실습 자료 내려받고 살펴보기

1. 터미널에서 실습 저장소를 내려받습니다(명령은 아래).
   • 확인: harness_eng_with, harness_eng_without 두 폴더와 맨 위의 CLAUDE.md, README.md가 보입니다.

git clone https://github.com/jaypakdevkr/harness_eng.git
cd harness_eng

2. harness_eng_with/AGENTS.md와 PLAN.md를 열어 위에서 설명한 규칙과 계획을 읽습니다.
3. harness_eng_with/evals/eval_samples.json을 엽니다.
   • 확인: 마감일이 지난 공고는 화면에 보이지 않아야 한다(expected_visible: false)는 식의 테스트 샘플이 들어 있습니다.
4. harness_eng_with/skills 안의 스킬 네 개를 열어 봅니다. QA, 출시 준비, 데이터 수집, UI 점검 단계용입니다.
5. harness_eng_without/README.md를 엽니다.
   • 확인: 프롬프트 한 줄 외에는 아무 지시도 없습니다.

2. 두 폴더에서 Codex로 따로 만들기

6. harness_eng_with 폴더에서 Codex 스레드(대화)를 새로 열고 작업을 시킵니다. 예시 문장은 아래와 같습니다.
   • 확인: Codex가 AGENTS.md와 PLAN.md를 읽었다고 알리고 단계별로 구현을 시작합니다.

AGENTS.md와 PLAN.md를 읽고, 거기 적힌 완료 조건을 모두 만족할 때까지 웹서비스를 구현해 줘. 단계마다 lint, test, build를 실행해서 결과를 보여 줘.

7. harness_eng_without 폴더에서 별도의 Codex 스레드를 열고, README.md의 프롬프트를 그대로 넣습니다.
   • 확인: 두 스레드가 서로의 폴더를 보지 않도록 각각 다른 폴더에서 열렸습니다.

3. Claude Code로 채점하기

8. 채점 전에 harness_eng_with 폴더의 AGENTS.md, PLAN.md, skills, evals를 지우거나 다른 곳으로 옮깁니다.
   • 이유: 평가하는 AI가 지시 파일을 보면 "당연히 이쪽이 잘했겠지"라고 치우쳐 채점할 수 있습니다.
   • 주의: 원본이 필요하면 복사본 폴더에서 작업합니다. 지운 파일은 저장소에서 다시 받을 수 있습니다.
9. 저장소 맨 위 폴더에서 Claude Code를 엽니다. 맨 위 CLAUDE.md에 "생성이 아니라 평가가 역할"이라는 평가 원칙이 이미 적혀 있습니다.
10. 맨 위 README.md에 적힌 채점 지시문을 Claude Code에 그대로 넣습니다. 지시문의 채점표는 7개 항목, 100점 만점입니다.

11. 이어서 결과를 파일로 남기라고 지시합니다(문장은 아래).
    • 확인: comparison_report.md에 총점 비교표, 항목별 비교, 치명적 결함, 최종 판정이 들어 있습니다.

최종 결과를 comparison_report.md 파일로 작성하라.

결과: 같은 모델, 다른 결과물

이 저장소 그대로 돌린 한 번의 비교에서 나온 점수입니다. 공개 벤치마크가 아니라 위 7개 항목 채점표로 Claude Code가 매긴 점수라서, 직접 해 보면 숫자는 달라질 수 있습니다.

• 기능 완성도: 지시 파일 있는 쪽 17점, 없는 쪽 14점
• 데이터 품질⁠·정규화: 18점 대 12점
• UI: 오히려 지시 파일이 없는 쪽이 더 좋다는 평가
• 7개 항목 합계: 88점 대 52점

점수가 갈린 이유

코드를 열어 보면 차이가 분명합니다.

프롬프트만 준 쪽은 겉으로는 잘 돌아가는 것처럼 보였지만, 실제 데이터가 아니라 코드 안에 박아 넣은 가짜 데이터(목 데이터)로 화면을 만들었습니다. 빌드가 실패하기도 했고, 테스트를 하지 않았고, README도 없었고, 큰 파일 하나에 모든 코드가 들어 있었습니다.

지시 파일을 갖춘 쪽은 K-Startup 같은 실제 공고 사이트에서 데이터를 모아 화면에 보여 줬습니다. 모은 데이터를 파싱하고 정규화해서 화면에 연결했고, 빌드가 됐고, 테스트와 검증까지 끝난 상태였습니다. README 같은 문서와 나뉜 파일 구조도 갖췄습니다.

눈여겨볼 차이는 UI가 아니라 데이터입니다. 데이터 품질 18점 대 12점이 그 차이를 보여 줍니다. 지시 파일은 화면을 예쁘게 만들기보다, 실제로 운영 가능한 상태로 개발하게 돕는 쪽에 효과가 컸습니다.

내 프로젝트에 하네스 심는 순서

하네스 엔지니어링은 거창한 마법이 아니라 이런 일입니다.

1. AGENTS.md로 규칙과 완료 조건을 고정합니다.
2. PLANS.md(또는 PLAN.md)로 이번 작업의 계획과 위험 요소를 적습니다.
3. 반복되는 검증 절차는 스킬 파일로 떼어 .agents/skills에 둡니다.
4. 정답 형태의 샘플 데이터와 평가 지시문까지 미리 준비합니다.

한마디로 팀이 일하는 방식을 AI가 읽을 수 있는 파일로 저장소 안에 심어 두는 것입니다. 그냥 만들어 달라고 하면 AI는 보기 좋은 수준의 코드를 쓰고 "다 만들었다"고 보고합니다. 지시 파일을 심어 두면 점점 운영 가능한 수준의 코드를 쓰게 됩니다.