들어가며

오늘은 Harness, CLAUDE.md, AGENTS.md가 각각 어떤 역할을 하는지 정리해봤다.

처음 이름만 보면 셋 다 작업을 더 효율적으로 도와주는 무언가처럼 느껴진다. 하지만 실제로는 다루는 대상도 다르고, 사용되는 맥락도 분명히 다르다.

  • Harness는 소프트웨어를 안전하게 배포하기 위한 운영 플랫폼이다.
  • CLAUDE.md는 AI에게 프로젝트 규칙을 알려주는 문서다.
  • AGENTS.md는 AI의 역할 분담과 작업 흐름을 정의하는 문서다.

즉, Harness는 실제 서비스 전달 과정을 다루는 도구이고, CLAUDE.md와 AGENTS.md는 AI가 프로젝트 안에서 더 정확하고 일관되게 작업하도록 돕는 가이드 문서라고 이해하면 된다.

Harness란

Harness는 빌드, 테스트, 배포, 검증, 롤백 같은 과정을 자동화하고 관리하는 플랫폼이다.

개발에서는 코드를 작성하는 것만으로 일이 끝나지 않는다. 작성한 코드가 실제 운영 환경까지 안전하게 전달되어야 하고, 그 과정에서 문제가 생기면 빠르게 감지하고 되돌릴 수 있어야 한다. 이때 필요한 것이 바로 배포 흐름의 자동화다.

예전에는 사람이 직접 서버에 접속해서 명령어를 실행하거나, 배포 순서를 기억해서 수동으로 진행하는 경우가 많았다. 하지만 서비스 규모가 커질수록 이런 방식은 실수 가능성이 높고, 같은 작업을 반복하더라도 품질을 일정하게 유지하기 어렵다. Harness는 이 과정을 파이프라인으로 정의해 누가 실행하더라도 같은 절차와 기준으로 배포가 이루어지게 돕는다.

왜 필요한가

서비스를 배포할 때는 보통 다음과 같은 흐름이 필요하다.

  1. 빌드
  2. 테스트
  3. 배포
  4. 배포 후 검증
  5. 장애 발생 시 롤백

이 과정을 전부 사람이 수동으로 처리하면 몇 가지 문제가 생긴다.

  • 실수가 발생하기 쉽다.
  • 배포 속도가 느려진다.
  • 팀원마다 방식이 달라 일관성이 깨질 수 있다.
  • 문제가 발생했을 때 원인 추적과 복구가 어려워진다.

결국 배포는 단순히 애플리케이션을 서버에 올리는 작업이 아니라, 서비스 품질을 유지하기 위한 운영 절차의 일부라고 볼 수 있다. Harness는 바로 이 절차를 자동화하고 표준화하는 데 초점이 맞춰져 있다.

핵심 특징

  1. 자동화
    • 코드 변경 이후 빌드, 테스트, 배포를 자동으로 실행할 수 있다.
  2. 안정성
    • 배포 중 이상이 감지되면 중단하거나 이전 버전으로 롤백할 수 있다.
  3. 표준화
    • 팀 전체가 동일한 배포 절차를 공유할 수 있다.
  4. 가시성
    • 현재 배포가 어느 단계에 있는지, 어디서 실패했는지 확인하기 쉽다.

예시로 보면

예를 들어 쇼핑몰 서비스의 결제 기능을 수정했다고 가정해보자. 개발자가 코드를 main 브랜치에 머지하면 아래와 같은 흐름이 자동으로 실행될 수 있다.

  1. 애플리케이션 빌드
  2. 자동 테스트 실행
  3. 스테이징 서버 배포
  4. 정상 동작 여부 확인
  5. 운영 서버 배포
  6. 오류 발생 시 자동 롤백

이런 흐름이 없다면 배포 이후 문제가 생겼을 때 누가 어떤 순서로 무엇을 해야 하는지 혼란이 생기기 쉽다. 반면 Harness를 사용하면 배포 과정 자체를 하나의 관리 가능한 시스템으로 다룰 수 있다.

장점과 한계

Harness의 가장 큰 장점은 사람이 하던 반복 작업을 줄이고, 배포를 더 안정적으로 만들 수 있다는 점이다. 배포 이력을 추적하기 쉽고, 승인 단계나 검증 단계도 체계적으로 넣을 수 있다.

다만 자동화가 많아질수록 파이프라인 설계가 복잡해질 수 있다. 그래서 단순히 도구를 도입하는 것보다, 어떤 기준으로 배포를 운영할 것인지 먼저 정리하는 것이 중요하다.

CLAUDE.md란

CLAUDE.md는 AI가 프로젝트 안에서 작업할 때 참고하는 규칙 문서다.

이름만 보면 Claude 전용 문서처럼 느껴질 수 있지만, 실제로 담기는 내용은 특정 AI 하나에만 해당되는 경우가 많지 않다. 프로젝트 구조, 실행 방법, 코딩 규칙, 수정하면 안 되는 부분 같은 정보는 대부분의 AI 코딩 도구가 공통으로 필요로 하는 문맥이다.

사람이 새로운 프로젝트에 참여할 때도 먼저 프로젝트 구조, 실행 방법, 코딩 규칙, 수정하면 안 되는 부분 같은 내용을 전달받는다. AI도 마찬가지다. 이런 정보가 정리되어 있지 않으면 AI는 코드만 보고 맥락을 추측해야 하고, 그 과정에서 잘못된 가정을 할 가능성이 커진다.

CLAUDE.md는 이런 문제를 줄이기 위해 AI에게 프로젝트 문맥을 빠르게 전달하는 역할을 한다. 다만 중요한 것은 파일 이름 자체보다 그 안에 어떤 규칙과 기준이 정리되어 있는가이다.

보통 들어가는 내용

  • 프로젝트 개요
  • 실행 명령어
  • 테스트 방법
  • 코드 스타일 규칙
  • 수정하면 안 되는 영역
  • 작업 우선순위
  • 커밋 또는 리뷰 원칙

왜 필요한가

AI는 프로젝트의 암묵적 규칙을 자동으로 완벽하게 이해하지 못한다. 예를 들어 어떤 디렉터리는 건드리면 안 된다거나, 특정 파일명 규칙을 따라야 한다거나, 테스트를 반드시 돌려야 한다는 기준은 문서로 명확히 주어져야 한다.

이런 규칙이 CLAUDE.md에 잘 정리되어 있으면 AI는 더 적은 시행착오로 원하는 방향의 결과를 낼 수 있다. 반대로 문서가 오래되어 실제 프로젝트와 맞지 않으면 오히려 잘못된 기준을 따르게 될 위험도 있다.

정리하면 CLAUDE.md는 이름상으로는 Claude 계열 도구를 떠올리게 하지만, 실제 내용은 다른 AI 코딩 도구에도 충분히 적용될 수 있는 프로젝트 작업 설명서에 가깝다.

AGENTS.md란

AGENTS.md는 AI의 역할 분담과 작업 흐름을 정의하는 문서다.

CLAUDE.md가 프로젝트 전체에서 공통으로 지켜야 할 규칙에 가깝다면, AGENTS.md는 그 안에서 어떤 역할이 무엇을 담당하는지 더 구체적으로 나누는 문서라고 볼 수 있다.

예를 들어 하나의 AI가 모든 작업을 한 번에 처리하는 대신, 초안 작성, 기술 검토, 최종 점검처럼 역할을 나눠서 작업한다면 AGENTS.md가 유용해진다.

예시 역할

  • writer: 초안 작성
  • reviewer: 기술 정확성과 문장 품질 검토
  • publisher: 발행 전 형식 점검

왜 필요한가

역할이 나뉘면 책임도 명확해진다. 누가 초안을 작성하고, 누가 정확성을 검토하고, 누가 최종 형식을 확인하는지 정해져 있으면 작업 흐름이 훨씬 선명해진다.

특히 문서 작성, 코드 리뷰, 발행 점검처럼 단계가 분리되는 작업에서는 이런 역할 정의가 품질 관리에 도움이 된다. 다만 작은 프로젝트에서는 역할을 지나치게 세분화할 경우 오히려 관리 비용만 늘어날 수 있다.

결국 AGENTS.md는 AI 협업 워크플로우를 정리하는 문서라고 볼 수 있다.

세 가지의 차이

세 가지는 모두 작업 효율을 높이기 위한 수단이라는 공통점이 있지만, 집중하는 대상은 서로 다르다.

항목 용도 장점 단점
Harness 빌드, 테스트, 배포, 검증, 롤백 등 소프트웨어 전달 과정을 자동화하는 플랫폼 배포 표준화, 휴먼 에러 감소, 배포 상태 추적, 승인과 롤백 흐름 관리 가능 초기 설정이 복잡할 수 있고, 파이프라인 설계가 잘못되면 운영이 오히려 어려워질 수 있다
CLAUDE.md AI에게 프로젝트 규칙과 작업 기준을 알려주는 문서 프로젝트 문맥 전달이 빠르고, AI 작업 품질의 일관성을 높일 수 있다 문서가 오래되면 잘못된 가이드가 될 수 있고, 너무 길면 핵심 규칙이 묻힐 수 있다
AGENTS.md AI 역할 분담과 작업 흐름을 정의하는 문서 역할과 책임이 명확해지고, 초안-검토-점검 흐름을 체계화하기 좋다 작은 프로젝트에서는 과설계가 될 수 있고, 역할이 지나치게 많아지면 관리 비용이 커질 수 있다

이 표를 보면 Harness는 실제 운영 자동화에 가까운 개념이고, CLAUDE.md와 AGENTS.md는 AI가 프로젝트 안에서 더 잘 일하기 위한 문서라는 차이가 분명해진다. 그중에서도 CLAUDE.md는 공통 규칙에, AGENTS.md는 역할 분담과 흐름에 더 초점이 맞춰져 있다.

마무리

이번에 정리하면서 느낀 점은, 셋 다 결국 일을 더 잘하기 위한 도구이지만 해결하려는 문제가 서로 다르다는 것이다.

  • Harness는 코드가 운영 환경까지 안전하게 전달되도록 돕는다.
  • CLAUDE.md는 AI가 프로젝트 규칙을 정확히 이해하도록 돕는다.
  • AGENTS.md는 AI가 역할에 따라 체계적으로 협업하도록 돕는다.

즉, Harness는 개발과 운영을 연결하는 플랫폼이고, CLAUDE.md와 AGENTS.md는 AI와 프로젝트를 연결하는 문서라고 정리할 수 있다. 특히 CLAUDE.md는 특정 AI만을 위한 절대적인 규칙서라기보다, 여러 AI 도구에도 활용 가능한 공통 작업 가이드라는 관점으로 이해하는 것이 더 정확하다.

앞으로는 새로운 도구나 문서를 볼 때, 단순히 “무엇을 하는가”만 보는 것이 아니라 “어떤 문제를 해결하기 위해 존재하는가”까지 함께 생각해보면 더 이해가 잘 될 것 같다.