프로젝트별 AI 규칙 파일이 에이전트 품질을 바꾸는 이유

프로젝트별 AI 규칙 파일이 에이전트 품질을 바꾸는 이유

AI 에이전트를 조금만 오래 써 보면 금방 드는 생각이 있다. 같은 모델인데도 어떤 프로젝트에서는 결과가 안정적이고, 어떤 프로젝트에서는 매번 비슷한 설명을 다시 붙여야 한다는 점이다. 같은 사람, 같은 도구, 비슷한 작업인데도 결과 편차가 꽤 크다.

처음에는 이 차이를 모델 성능으로 설명하기 쉽다. 더 큰 모델을 쓰면 나아질까, 프롬프트를 더 길게 쓰면 될까, 시스템 프롬프트를 더 정교하게 다듬으면 해결될까 같은 쪽으로 먼저 생각하게 된다.

그런데 실제 운영에서는 다른 지점이 더 중요할 때가 많다. 이 프로젝트에서 에이전트가 무엇을 우선해야 하는지, 어떤 작업 흐름을 기본값으로 따라야 하는지, 어떤 파일을 먼저 읽고 어떤 범위를 건드리지 말아야 하는지가 구조화되어 있느냐가 결과를 크게 바꾼다.

최근 GeekNews에서도 .claude/ 폴더 구조를 분석한 글과 하네스/스킬 아키텍처 관련 글이 같이 보였다. 표면적으로는 다른 이야기 같지만, 결국 공통된 메시지는 비슷하다. 에이전트를 잘 쓰려면 모델 하나만 보는 게 아니라 프로젝트 로컬 규칙과 작업 구조를 같이 설계해야 한다는 점이다.

이 글에서는 왜 프로젝트별 규칙 파일과 스킬 구조가 중요한지, 그리고 실전에서는 어떤 식으로 나누는 편이 운영에 도움이 되는지 정리해 본다.

좋은 프롬프트 하나로 오래 버티기 어려운 이유

AI를 처음 붙일 때는 보통 프롬프트부터 시작한다.

• 이 프로젝트는 어떤 서비스인지 설명하고
• 코딩 스타일을 알려 주고
• 테스트 방법을 적어 두고
• 금지사항과 주의사항을 써 둔다

초반에는 이 방식이 잘 통한다. 시작 비용이 낮고, 당장 결과가 나오기 때문이다.

하지만 반복 작업이 늘면 곧 문제가 생긴다.

• 새 세션을 열 때마다 같은 배경 설명을 반복하게 된다
• 프로젝트가 커질수록 프롬프트 길이가 계속 늘어난다
• 작업 종류가 달라지면 지시 순서도 바뀐다
• 어떤 규칙은 중요한데 어떤 규칙은 참고 수준이라 우선순위가 흐려진다
• 팀이나 여러 에이전트가 같이 쓰기 시작하면 문구가 조금씩 달라진다

즉 프롬프트만으로 운영하면 정보는 많아지는데 구조는 약해진다. 결국 결과 품질이 모델 능력보다 운영자가 얼마나 매번 맥락을 잘 다시 주입하느냐에 좌우되기 쉽다.

프로젝트 로컬 규칙은 맥락을 매번 다시 설명하지 않게 해 준다

프로젝트별 규칙 파일이 필요한 이유는 단순하다. 이 프로젝트에서 반복되는 맥락을 작업장 안에 고정해 두기 위해서다.

예를 들어 아래 같은 정보는 세션마다 다시 말하기보다 프로젝트 안에 두는 편이 낫다.

• 저장소의 목적과 주요 디렉터리 구조
• 코딩 스타일과 네이밍 규칙
• 테스트/빌드/검증 명령
• 수정하면 안 되는 민감한 경로
• PR 작성 규칙, 커밋 메시지 규칙
• 문서 작성 말투와 포맷
• 사람이 꼭 검토해야 하는 단계

이 정보가 프로젝트에 붙어 있으면 에이전트는 단순히 모델 응답기가 아니라 프로젝트에 맞춰 길들여진 작업자에 조금 더 가까워진다.

그래서 .claude/, AGENTS.md, SKILL.md, 작업용 체크리스트 파일, 프로젝트별 메모 파일 같은 구조가 점점 중요해진다. 이름은 달라도 역할은 비슷하다. 이 저장소에서 통하는 규칙을 저장소 안에 두는 것이다.

중요한 건 규칙을 한 파일에 다 몰아넣는 게 아니다

프로젝트 로컬 규칙을 만들 때 흔히 하는 실수는 모든 걸 한 문서에 몰아넣는 것이다. 이렇게 되면 처음에는 편해 보여도 나중에는 다시 거대한 시스템 프롬프트가 된다.

내가 보기엔 아래처럼 나누는 쪽이 훨씬 오래 간다.

1. 기본 정체성 파일

이 프로젝트가 무엇인지, 어떤 태도로 작업해야 하는지, 기본 금지사항이 무엇인지를 적는 파일이다.

여기에는 보통 이런 내용이 들어간다.

• 프로젝트 목적
• 사용자/독자/고객이 누구인지
• 절대 건드리면 안 되는 것
• 기본 작업 순서
• 외부 전송 전 확인 원칙

이건 프로젝트의 “헌법” 같은 역할에 가깝다. 너무 장황할 필요는 없지만, 방향을 흔들리지 않게 잡아 줘야 한다.

2. 작업 종류별 스킬 또는 체크리스트

블로그 작성, 코드 리뷰, 배포 점검, 이슈 triage처럼 반복 작업은 종류별로 따로 빼 두는 편이 좋다.

예를 들면:

• 블로그 초안 작성용 skill
• PR 리뷰용 checklist
• 장애 대응용 runbook
• 릴리스 전 점검용 문서

이렇게 분리해 두면 공통 규칙은 유지하면서도 작업 종류에 따라 필요한 단계만 불러올 수 있다. 매번 모든 규칙을 다 읽게 만드는 것보다 훨씬 효율적이다.

3. 로컬 메모리 또는 운영 기록

프로젝트에서 최근 무슨 결정을 했는지, 어떤 문제가 반복됐는지, 무엇을 이미 시도했는지 같은 정보는 별도 메모리 파일로 관리하는 편이 낫다.

이건 장기적으로 꽤 중요하다. 에이전트가 매번 처음 보는 저장소처럼 행동하지 않게 해 주기 때문이다.

예를 들어 아래 같은 정보는 메모리 계층에 잘 맞는다.

• 최근 합의한 아키텍처 결정
• 이미 실패한 접근
• 자주 발생하는 CI 오류 패턴
• 특정 운영 환경의 주의사항
• 이번 주 우선순위

규칙 파일이 “어떻게 행동할지”를 정의한다면, 메모리 파일은 “지금 무엇을 알고 있어야 하는지”를 보완한다.

왜 이 구조가 결과 품질을 실제로 바꾸는가

여기서 핵심은 단지 문서를 정리하는 문제가 아니다. 이 구조는 결과 품질을 만드는 네 가지 요소와 직접 연결된다.

1. 일관성

규칙이 프로젝트 안에 있으면 세션이 바뀌어도 기본 태도가 유지된다. 같은 모델을 써도 결과 편차가 줄어드는 이유다.

2. 속도

반복 설명이 줄어든다. 작업 시작 전에 매번 프로젝트 설명을 장문으로 붙일 필요가 없으니 실제 작업 진입 속도가 빨라진다.

3. 안전성

수정 금지 경로, 승인 필요 단계, 외부 전송 조건 같은 것이 로컬 규칙으로 남아 있으면 실수 가능성이 줄어든다. 특히 여러 도구를 같이 쓸 때 효과가 크다.

4. 협업 가능성

한 사람만 쓰는 프롬프트에서 벗어나 팀이나 여러 에이전트가 공유 가능한 운영 규칙으로 바뀐다. 이 차이가 커질수록 에이전트 활용이 개인 실험에서 운영 체계로 넘어간다.

실전에서는 무엇을 프로젝트에 넣고, 무엇을 밖에 둘까

이 구분도 중요하다. 모든 것을 프로젝트에 넣는 게 정답은 아니다.

내 기준으로는 보통 이렇게 나누는 편이 좋다.

프로젝트 안에 둘 것

• 저장소 구조 설명
• 빌드/테스트/검증 방법
• 문서 스타일 규칙
• 작업 순서와 승인 지점
• 팀 공용 체크리스트
• 프로젝트 특화 메모

프로젝트 밖에 둘 것

• 개인 계정 정보
• API 키, 토큰, 비밀값
• 개인 습관 수준의 메모
• 다른 프로젝트와 공유하면 안 되는 민감 정보
• 환경 전체를 넓게 여는 권한 설정

이렇게 나눠야 프로젝트를 옮기거나 공유할 때도 안전하다. 에이전트 품질을 올리겠다고 민감한 개인 정보까지 규칙 파일에 섞어 넣는 건 좋은 방법이 아니다.

결국 중요한 건 “규칙”보다 “불러오기 쉬운 구조”다

프로젝트 로컬 규칙 파일을 잘 만드는 팀을 보면 공통점이 있다. 규칙 내용 자체도 중요하지만, 언제 어떤 규칙을 읽게 할지가 더 잘 설계되어 있다.

예를 들어:

• 기본 세션에서는 프로젝트 정체성 파일만 읽는다
• 블로그 작업이면 블로그 skill만 추가로 읽는다
• PR 리뷰면 리뷰 checklist만 읽는다
• 장기 운영 작업이면 최근 메모리 파일을 같이 본다

이런 식의 계층이 있으면 컨텍스트를 덜 낭비하면서도 필요한 규칙을 더 정확히 적용할 수 있다.

반대로 모든 세션에서 모든 문서를 읽게 만들면 컨텍스트는 금방 비싸지고, 정말 중요한 규칙이 묻히기 쉽다. 구조가 없으면 정보량이 늘수록 오히려 품질이 떨어진다.

내가 선호하는 최소 구성

아주 거창하게 시작할 필요는 없다. 처음에는 아래 정도만 있어도 충분히 체감이 난다.

1. 프로젝트 루트 안내 파일 하나

이 저장소가 무엇이고, 무엇이 중요한지, 어떤 경로를 우선 봐야 하는지 정리한다.

2. 반복 작업용 skill 또는 checklist 2~3개

실제로 자주 하는 일부터 분리한다. 예를 들면 문서 작성, 코드 수정, 리뷰 정도다.

3. 최근 결정과 운영 이슈를 적는 메모 파일 하나

반복되는 실수와 최근 맥락을 누적한다.

4. 위험 작업 전 승인 규칙 한 줄

삭제, 외부 전송, 대량 변경처럼 위험한 작업은 어디서 멈출지 명확히 적어 둔다.

이 정도만 있어도 프롬프트를 매번 길게 붙이는 것보다 훨씬 안정적이다.

이 구조는 특정 도구 전용이 아니라는 점도 중요하다

.claude/ 폴더든, AGENTS.md든, SKILL.md든, 내부 운영 문서든 형식은 중요하지 않다. 중요한 건 특정 도구 이름이 아니라 프로젝트가 에이전트를 맞이할 준비가 되어 있느냐다.

도구는 바뀔 수 있다. Claude Code를 쓰다가 Codex를 더 많이 쓸 수도 있고, OpenClaw 같은 오케스트레이션 계층을 붙일 수도 있고, 다른 작업기를 추가할 수도 있다. 하지만 프로젝트 로컬 규칙과 작업 구조가 잘 잡혀 있으면 도구가 바뀌어도 운영 지식이 남는다.

그래서 이 구조는 단기 팁이 아니라 장기 자산에 가깝다.

마무리

AI 에이전트 활용이 길어질수록 모델 선택만으로는 설명되지 않는 차이가 커진다. 어떤 프로젝트는 같은 모델인데도 계속 안정적이고, 어떤 프로젝트는 매번 새로 길들이는 느낌이 든다.

이 차이를 만드는 건 종종 더 비싼 모델이 아니라 프로젝트에 규칙과 작업 구조가 내장되어 있느냐다.

정리하면 이렇다.

• 좋은 프롬프트 하나만으로는 반복 작업을 오래 버티기 어렵다
• 프로젝트 로컬 규칙은 반복 맥락을 저장소 안에 고정해 준다
• 기본 규칙, 작업별 스킬, 운영 메모리는 분리하는 편이 좋다
• 이 구조는 일관성, 속도, 안전성, 협업성을 같이 올린다
• 중요한 건 문서 양보다 불러오기 쉬운 계층 구조다

에이전트를 프로젝트에 더 깊게 붙일 생각이라면, 다음에는 프롬프트 문구를 한 줄 더 다듬기 전에 먼저 이 저장소에는 어떤 규칙 파일과 어떤 작업 스킬이 있어야 하는가부터 정리해 보는 편을 추천한다.

status: drafted