md 파일로 AI의 작업 환경을 만드세요

1. md 파일이 뭔가요?

md는 마크다운(Markdown)의 줄임말로, 확장자가 .md인 글자 파일입니다. 메모장으로 열리는 평범한 글인데, #, - 같은 간단한 기호로 제목, 목록, 코드 상자를 표시합니다. 2004년 존 그루버(John Gruber)가 에런 스워츠(Aaron Swartz)와 함께 ‘그대로 읽어도 읽기 쉬운 글’을 목표로 만든 형식입니다. 워드나 한글 파일과 달리 글꼴이나 색 같은 꾸밈 정보가 없어서 어떤 프로그램에서든 열리고, 사람과 AI 모두 쉽게 읽습니다.

# 큰 제목

- 목록 항목 하나
- 목록 항목 둘

**굵은 글씨**로 강조

왼쪽처럼 쓰면 마크다운을 지원하는 화면에서 오른쪽처럼 보입니다.

2. 하네스 엔지니어링이 뭔가요?

하네스(harness)는 말이 마차나 쟁기를 끌 수 있도록 몸에 채우는 마구(장구)를 뜻하는 말입니다. 힘센 말도 마구가 없으면 그 힘을 원하는 방향으로 쓰게 하기 어렵습니다. AI도 마찬가지로, 모델 자체가 아무리 똑똑해도 무슨 일을, 어떤 규칙으로, 어떤 도구로, 어떻게 확인하며 할지가 정해져 있지 않으면 매번 결과가 들쭉날쭉합니다.

하네스 엔지니어링은 이 ‘모델을 뺀 나머지 전부’, 즉 지시문, 규칙, 참고 자료, 사용할 도구, 검증 절차를 설계하는 일입니다. ‘에이전트 = 모델 + 하네스’라는 식으로도 설명하며, 2026년 초 미첼 하시모토(HashiCorp 공동 창업자)의 글과 OpenAI의 Codex 사례 글을 계기로 널리 쓰이기 시작했습니다. 파일, 규칙 외에도 테스트, 권한 설정, 자동 검사 같은 장치가 모두 하네스에 포함됩니다.

흔히 이렇게 구분하며, 뒤로 갈수록 다루는 범위가 넓어집니다. 질문을 잘 쓰는 것에서 시작해, 결국 ‘AI가 실수하기 어려운 환경’을 만드는 쪽으로 관심이 옮겨가고 있습니다.

3. 왜 md 파일로 하네스를 만들까요?

• AI가 그대로 읽을 수 있습니다

  md는 꾸밈 없는 글자라서 변환 없이 AI에게 바로 전달됩니다. 제목(#)과 목록(-) 덕분에 구조도 잘 전달됩니다.

• 한 번 쓰면 계속 씁니다

  매번 같은 설명을 채팅창에 반복해서 입력하는 대신 파일에 한 번 적어두면 됩니다. AI 코딩 도구들은 작업을 시작할 때 정해진 이름의 규칙 파일을 자동으로 읽어 들입니다.

• 사람도 읽고 고칠 수 있습니다

  특별한 프로그램 없이 메모장으로 열립니다. 팀원이 함께 읽고, 틀린 규칙을 바로 고칠 수 있습니다.

• 기록과 공유가 쉽습니다

  파일이라서 변경 이력을 남기고, 되돌리고, 다른 사람에게 그대로 건네줄 수 있습니다. 잘 만든 하네스는 곧 재사용 가능한 자산입니다.

• 필요한 것만 불러서 아낄 수 있습니다

  파일을 주제별로 나눠두면 AI가 지금 일에 필요한 내용만 읽습니다. 관계없는 내용에 주의가 흩어질 일이 줄고, 읽는 양이 줄어 비용도 아낍니다.

4. 하네스를 이루는 md 파일들

도구마다 파일 이름과 위치는 조금씩 다르지만, 역할은 비슷합니다. 대표적인 것들입니다.

• 프로젝트 규칙 파일AGENTS.md · CLAUDE.md 등

  AI가 일을 시작할 때 가장 먼저 읽는 파일. 빌드·테스트 명령어, 지켜야 할 규칙 등을 적어둡니다. AGENTS.md는 여러 AI 코딩 도구가 함께 쓰는 공개 형식이고, CLAUDE.md는 Claude Code가 읽는 파일입니다.

• 스킬(작업 절차서)SKILL.md 등

  '리뷰 쓰는 법', '배포하는 순서'처럼 특정 작업의 절차를 담은 파일. 평소에는 이름과 설명만 보이다가, 관련된 일을 할 때만 전체 내용을 불러옵니다.

• 명령어·역할 정의commands/*.md, agents/*.md 등

  자주 시키는 일을 한 줄 명령어로 만들거나, '검토 담당' 같은 역할을 따로 정의한 파일.

• 계획서·명세서PLAN.md · SPEC.md 등

  무엇을 만들지, 어떤 순서로 할지, 언제 끝난 것으로 볼지를 적은 문서. 큰 작업을 쪼개서 맡길 때 씁니다.

• 인수인계·진행 기록NOTES.md · 세션 요약 등

  AI는 대부분 새 대화를 시작하면 이전 내용을 기억하지 못하기 때문에, 한 일과 남은 일을 파일로 남겨 다음 작업에서 이어받게 합니다.

5. 이렇게 시작해보세요

거창하게 시작할 필요 없습니다. 매번 반복해서 말하던 지시부터 규칙 파일 하나에 이 정도로 옮겨 적어보세요.

# 프로젝트 규칙

## 자주 쓰는 명령어
- 개발 서버 실행: `npm run dev`
- 테스트: `npm test`

## 작업 규칙
- 코드를 고친 뒤에는 반드시 `npm test`를 실행하고 결과를 알려줘
- 새 함수에는 한국어 주석으로 "언제 쓰이는지"를 한 줄 적어줘
- 이유: 비개발자 팀원도 코드를 읽어야 해서

## 하지 말 것
- .env 파일 내용을 출력하지 말 것
- 시키지 않은 파일은 지우지 말 것

6. 잘 활용하는 방법

1. 1

   짧고 구체적으로 쓰세요

   '코드를 깔끔하게'보다 '함수 하나는 40줄을 넘기지 않기'가 낫습니다. 프로젝트 소개를 길게 쓰기보다 구체적인 지시를 적는 편이 효과적이고, 파일이 너무 길면 중요한 규칙이 묻히고 비용만 늘어납니다.

2. 2

   규칙에는 이유를 함께 적으세요

   이유를 알면 AI가 예외 상황에서도 규칙의 취지에 맞게 판단합니다. 위 예시의 '비개발자도 읽어야 해서'처럼 한 줄이면 충분합니다.

3. 3

   끝났다는 기준을 알려주세요

   '테스트를 돌려서 통과하면 끝', '화면을 열어서 확인하기'처럼 스스로 검증할 방법을 적어두면 AI가 결과를 확인하고 고치는 데까지 갑니다.

4. 4

   AI가 실수할 때마다 한 줄씩 추가하세요

   처음부터 완벽하게 쓰려 하지 마세요. 같은 실수가 반복될 때 그 방지 규칙을 추가하면, 쓸수록 하네스가 단단해집니다.

5. 5

   역할과 주제별로 파일을 나누세요

   '공통 규칙', '배포 절차', '디자인 규칙'처럼 나누면 관리하기 쉽고, 필요한 파일만 불러올 수 있습니다.

6. 6

   낡은 내용은 지우세요

   프로젝트가 바뀌었는데 규칙이 그대로면 AI가 옛날 방식으로 일합니다. 가끔 읽어보고 맞지 않는 줄은 정리하세요.

7. 7

   중요한 금지는 md 파일에만 맡기지 마세요

   md 파일의 규칙은 강제가 아니라 '부탁'이라서 AI가 놓칠 수 있습니다. 파일 삭제나 외부 전송처럼 꼭 막아야 하는 일은 도구의 권한 설정이나 자동 검사로 함께 막으세요.

8. 8

   비밀번호·키는 절대 적지 마세요

   md 파일은 AI와 팀원, 때로는 저장소를 통해 다른 사람에게도 보입니다. 비밀번호나 API 키는 넣지 않습니다.