AI 코딩 에이전트에 더 나은 저장소 컨텍스트 제공
AI 코딩 에이전트는 수신하는 컨텍스트만큼만 유용합니다. 프로젝트가 어떻게 구성되어 있는지, 테스트가 어떻게 실행되는지, 어떤 파일을 편집해도 안전한지, 팀이 따르는 규칙이 무엇인지 모르는 경우에는 합리적으로 보이지만 작업 흐름을 깨뜨리는 코드를 작성할 수 있습니다. 이것이 바로 AGENTS.md 모범 사례가 중요한 이유입니다. 이 가이드에서는 AGENTS.md이 무엇인지, 무엇을 포함해야 하는지, 무엇을 피해야 하는지, EasyClaw과 같은 워크플로 에이전트가 정적 저장소 지침을 반복 가능한 AI 코딩 워크플로로 전환하는 데 어떻게 도움이 될 수 있는지 설명합니다.
AGENTS.md란 무엇입니까?
AGENTS.md은 AI 코딩 에이전트에 프로젝트별 지침을 제공하는 마크다운 파일입니다. 공식 AGENTS.md 사이트에서는 에이전트를 위한 README와 유사한 장소, 즉 설정 명령, 테스트 명령, 코드 스타일, 프로젝트 구조 및 경계를 찾을 수 있는 예측 가능한 파일이라고 설명합니다.
README.md, 테스트, 코드 검토 또는 인간의 판단을 대체하지 않습니다. 전체 프로젝트 백과사전이나 긴 건축 에세이가 되어서는 안 됩니다. 그 작업은 더 좁습니다. 코딩 에이전트에게 안전하게 행동하는 데 필요한 저장소 컨텍스트를 제공합니다.
GitHub Copilot 코딩 에이전트는 특정 저장소 영역에 대한 루트 수준 파일 및 중첩 파일을 포함하여 AGENTS.md 사용자 정의 지침을 지원합니다. 이는 패턴을 팀에 유용하게 만들지만 품질 기준도 높입니다. 나쁜 AGENTS.md은 좋은 에이전트가 안내하는 것처럼 쉽게 에이전트를 오도할 수 있습니다.
AGENTS.md가 AI 코딩 에이전트에 중요한 이유
AI 코딩 에이전트에는 운영 컨텍스트가 필요합니다. 중요한 파일이 어디에 있는지, 종속성이 어떻게 설치되는지, 테스트가 어떻게 실행되는지, 어떤 린트 또는 유형 검사가 필요한지, 어떤 프레임워크 버전이 중요한지, 어떤 디렉토리가 금지되어 있는지, 깔끔한 PR에 무엇을 포함해야 하는지 등이 필요합니다.
좋은 AGENTS.md은 추측을 줄여줍니다. 잘못된 AGENTS.md은 새로운 추측을 만들어냅니다.
연구는 여전히 혼합되어 있습니다. 맥락이 구체적일 때는 도움이 되지만, 불필요한 요구 사항이 추가되면 해로울 수 있습니다. 실용적인 내용은 간단합니다. 인간이 에이전트가 따르기를 원하는 최소한의 유용한 컨텍스트를 작성합니다.
AGENTS.md 모범 사례: 포함할 내용
1. 프로젝트 개요
프로젝트 목적, 언어, 프레임워크, 런타임, 패키지 관리자, 주요 디렉터리 등 개요를 짧게 유지하세요.
나쁨: “이것은 최신 웹 앱입니다.”
더 좋음: "이것은 TypeScript, pnpm, Prisma 및 PostgreSQL을 사용하는 Next.js 앱입니다. 앱 코드는 /app에 있고, 공유 UI는 /components에, 스키마는 /prisma/schema.prisma에 있습니다."
2. 설정 명령
상담원은 패키지 관리자나 스크립트를 추측해서는 안 됩니다. 실제로 작동하는 명령을 포함합니다.
- 종속성 설치:
pnpm install - 개발 서버 시작:
pnpm dev - 빌드:
pnpm build - 실행 유형 확인:
pnpm typecheck
설정에 제한이 있는 경우 그렇게 말하세요. “E2E 테스트에는 Docker가 필요합니다. “테스트 실행”보다 낫습니다.
3. 테스트 명령
테스트 지침은 Agent.md 파일에서 가장 중요한 부분 중 하나입니다. 전체 테스트 명령, 집중 테스트 명령, 관련되는 경우 통합 또는 E2E 명령 및 알려진 테스트 제한 사항을 포함합니다.
- 모든 테스트 실행:
pnpm test - 하나의 파일 실행:
pnpm test path/to/file.test.ts - E2E 실행:
pnpm test:e2e - 린트 실행:
pnpm lint
또한 충분한 검증이 무엇인지 말해 보세요. 문서 변경사항과 인증 변경사항에는 동일한 확인이 필요하지 않습니다.
4. 프로젝트 구조
에이전트에 필요한 구조만 나열합니다. 경로의 경우 /app, UI의 경우 /components, 유틸리티의 경우 /lib, 백엔드 논리의 경우 /server, 픽스처의 경우 /tests, 스키마 및 마이그레이션의 경우 /prisma입니다. 생성된 폴더, 레거시 폴더 또는 위험한 폴더를 명확하게 표시합니다.
5. 코드 스타일 및 규칙
예제는 모호한 규칙을 이겼습니다. "깨끗한 코드를 사용하는 대신 동작에 영향을 미치는 규칙을 작성하세요.
- 공유 유틸리티에 대해 명명된 내보내기를 사용합니다.
- 서비스 계층 오류 처리에는
Result<T, E>을 사용하세요. - 테스트 이름을
should_do_expected_behavior_when_condition로 지정합니다. - 설비를 추가하기 전에
/tests/helpers의 기존 도우미를 선호하세요.
목표는 에이전트가 하나의 파일에서 추론할 수 없는 규칙을 인코딩하는 것입니다.
6. Git 및 PR 워크플로
분기 이름 지정, 커밋 정책, PR 요약 형식, 필수 확인 사항, 에이전트 커밋 가능 여부 등 검토를 위해 작업을 준비하는 방법을 에이전트에게 알려줍니다. 유용한 규칙은 "명시적으로 요청하지 않는 한 커밋하지 마십시오. 요약, 변경된 파일, 테스트 결과 및 위험 영역을 포함하십시오."입니다.
7. 경계 및 안전 규칙
경계는 기본 설정보다 더 유용한 경우가 많습니다.
.env파일을 편집하지 마세요.- 비밀, 토큰 또는 자격 증명을 커밋하지 마세요.
- 승인 없이 프로덕션 구성을 수정하지 마십시오.
- 묻지 않고 마이그레이션을 다시 작성하지 마십시오.
- 이유를 설명하지 않고 종속성을 추가하지 마세요.
- 인증, 권한 부여 또는 권한 확인을 약화시키지 마십시오.
8. 보안 및 완료의 정의
보안 지침을 직접적으로 유지하세요. 입력 유효성을 검사하고, 개인 데이터 로깅을 방지하고, 인증 확인을 유지하고, API 키를 노출하지 않고, 민감한 코드를 변경하기 전에 묻습니다.
그런 다음 “완료—
- 테스트 실행 또는 설명 제공.
- 관련이 있는 경우 Lint/typecheck가 실행됩니다.
- 동작이 변경되면 문서가 업데이트됩니다.
- PR 요약본을 준비했습니다.
- 위험한 지역이 언급되었습니다.
- 인증, 결제, 권한, 마이그레이션, 인프라 및 개인 데이터에 대한 인적 검토가 필요합니다.
AGENTS.md에 넣으면 안되는 것
더 많은 맥락이 항상 더 나은 것은 아닙니다. 긴 제품 기록, 오래된 아키텍처 에세이, 모순되는 규칙, 거대한 스타일 가이드, 중복된 README 콘텐츠, 일회성 작업 메모, 개인 자격 증명 및 상담원이 검토를 건너뛰도록 유도하는 지침을 피하세요.
"고품질 코드 작성" 또는 "조심하세요"와 같은 일반적인 필러는 피하세요.
간단한 규칙이 효과적입니다. 명령이 에이전트가 수행해야 하는 작업을 변경하지 않으면 제거하십시오.
AGENTS.md 템플릿
이를 시작점으로 사용한 다음 저장소에 맞게 지정하세요.
# AGENTS.md
프로젝트 개요
[프로젝트, 스택, 런타임, 패키지 관리자 및 주요 디렉터리에 대한 간단한 설명]
설정 명령
- 종속성 설치:
[command] - 개발 서버 시작:
[command] - 빌드:
[command]
테스트 명령
- 모든 테스트 실행:
[command] - 집중 테스트 실행:
[command] - Lint/typecheck 실행:
[command] - 알려진 테스트 제한 사항: [참고]
프로젝트 구조
[path]: [목적][path]: [목적]
코드 스타일
- [특정 스타일 규칙]
- [특정 패턴]
Git 작업흐름
- 지점 이름:
- 커밋 정책:
- PR 요약 형식:
- 필수 확인사항:
경계
- 편집하지 마십시오:
- 변경하기 전에 물어보세요:
- 절대 커밋하지 마세요:
보안 참고사항
- 비밀을 노출하지 마십시오.
- 인증 및 권한 확인을 유지합니다.
- 민감한 데이터를 기록하지 마세요.
완료의 정의
- 테스트 실행:
- Lint/typecheck 실행:
- 준비된 요약:
- 다음에 대해 사람의 검토가 필요합니다.
AGENTS.md 유지 관리 모범 사례
AGENTS.md은 코드처럼 유지되어야 합니다. 스크립트가 변경되거나, 디렉터리가 이동하거나, 테스트 명령의 이름이 변경되거나, 보안 규칙이 변경되거나, 팀이 새로운 코딩 에이전트를 채택할 때 이를 검토하세요.
오래된 결정을 담은 박물관이 되지 않도록 하십시오. 파일에 npm test이 표시되어 있지만 저장소에서 현재 pnpm test을 사용하는 경우 에이전트가 시간을 낭비할 수 있습니다. 에이전트에게 이전 구성 요소 패턴을 사용하도록 지시하면 더 이상 사용되지 않는 코드가 다시 활성화될 수 있습니다.
주요 리팩터링 중, 릴리스 전, 반복적인 에이전트 실패 후, 저장소를 AI 코딩 워크플로에 온보딩할 때 AGENTS.md을 확인하세요.
EasyClaw가 적합한 곳: 정적 컨텍스트에서 AI 코딩 워크플로까지
AGENTS.md은 코딩 에이전트에 정적 저장소 컨텍스트를 제공합니다. EasyClaw은 팀이 해당 컨텍스트를 실행 가능한 워크플로로 전환하는 데 도움이 됩니다.
그 구별이 중요합니다. Agent.md 파일은 에이전트에게 테스트가 진행 중인 위치를 알려줄 수 있지만 소스 파일을 구성하고, 실패한 로그를 수집하고, PR 요약을 패키지하고, 검토 역할을 조정하거나, 팀 업데이트를 보내지는 않습니다.
EasyClaw은 사용자가 지저분한 작업을 실행 가능한 워크플로로 전환하는 데 도움이 되는 Mac 및 Windows용 데스크톱 기반 AI 에이전트입니다. 개발자의 경우 리포지토리, 브라우저 문서, 터미널 출력, 테스트 로그, PR 노트, 릴리스 노트 및 검토 체크리스트를 구성하는 데 도움이 될 수 있습니다.
EasyClaw은 AGENTS.md를 대체하지 않습니다. AGENTS.md은 저장소 지침을 정의합니다. EasyClaw은 주변 AI 개발자 워크플로를 실행하는 데 도움이 됩니다.
EasyClaw는 AGENTS.md 컨텍스트를 구성할 수 있습니다.
코딩 작업을 할당하기 전에 EasyClaw은 워크플로우에 준비된 컨텍스트 패킷을 준비하는 데 도움을 줄 수 있습니다.
- 관련 AGENTS.md 지침
- 소스 파일과 변경된 파일
- 설정 및 테스트 명령
- 합격기준
- 알려진 경계
- 위험 참고 사항
- 예상 PR 요약 형식
EasyClaw는 다중 에이전트 개발 워크플로우를 지원합니다
코딩 에이전트 작업이 단일 역할인 경우는 거의 없습니다. EasyClaw은 각 역할에 정의된 작업이 있는 다중 에이전트 워크플로를 지원할 수 있습니다.
- 저장소 컨텍스트 에이전트: AGENTS.md을 읽고 프로젝트 규칙을 요약합니다.
- 요구사항 에이전트: 허용 기준과 비목표를 추출합니다.
- 구현 에이전트: 작은 코드 변경을 제안합니다.
- 테스트 에이전트: 단위, 통합 및 집중 테스트 명령을 확인합니다.
- 실패 분석 에이전트: 실패한 테스트 로그를 요약합니다.
- 보안 검토 에이전트: 민감한 코드 경로에 플래그를 지정합니다.
- 문서 에이전트: PR 요약 및 릴리스 노트 초안을 작성합니다.
- 검토 대리인: 인간의 승인을 위해 불확실한 주장을 표시합니다.
이는 각 에이전트가 제한된 역할과 검토 가능한 출력을 갖기 때문에 하나의 거대 "이 저장소를 수정하라는 메시지"보다 더 강력합니다.
EasyClaw는 인간을 지속적으로 추적합니다.
AGENTS.md이나 EasyClaw 모두 프로덕션 코드만 승인해서는 안 됩니다. 인간 검토자는 여전히 아키텍처 판단, 보안 결정, 테스트 품질 및 병합 승인을 소유합니다.
EasyClaw은 체크포인트 생성을 도울 수 있습니다. 작업 계획 승인, 생성된 코드 검토, 실패한 로그 분석 검사, 보안에 민감한 변경 사항 확인, 작업 병합 준비 여부 결정 등이 가능합니다.
EasyClaw는 예약 및 채팅으로 트리거되는 워크플로를 지원합니다.
AGENTS.md 유지 관리는 잊어버리기 쉽습니다. EasyClaw은 주간 AGENTS.md 검토, 야간 실패 테스트 요약, 공개 PR 요약, 사전 출시 체크리스트 및 종속성 위험 메모와 같은 예약된 워크플로를 지원할 수 있습니다.
엔지니어링 팀은 Slack, Discord, Telegram 또는 Teams에서도 조정합니다. EasyClaw은 다음과 같은 채팅으로 트리거되는 워크플로를 지원할 수 있습니다.
“AGENTS.md 파일을 검토하고, 패키지 스크립트와 비교하고, 개선 사항을 준비하세요.”
또는:
“최신 브랜치에서 실패한 테스트를 요약하고 PR 리뷰 패킷을 준비하세요.”
EasyClaw는 RPA 스타일 개발자 워크플로를 지원합니다.
AI 코딩 워크플로는 종종 IDE, 터미널, 브라우저, GitHub 또는 GitLab 페이지, 로컬 파일, 문서, 스프레드시트, Slack 스레드 및 릴리스 노트 등 도구를 교차합니다. EasyClaw은 컨텍스트 수집, 로그 그룹화, 요약 준비, 보고서 패키징, 출력을 올바른 위치로 이동 등 이러한 도구를 중심으로 RPA 스타일 데스크톱 워크플로 구성을 도울 수 있습니다.
이것이 바로 EasyClaw이 AGENTS.md을 보완하는 부분입니다. 파일은 지침을 제공하고 워크플로 계층은 지침을 반복 가능한 엔지니어링 작업으로 전환합니다.
EasyClaw AGENTS.md 워크플로 예
팀이 TypeScript 단일 저장소 전체에서 코딩 에이전트 안정성을 향상시키고 싶어한다고 상상해 보십시오.
입력: 기존 AGENTS.md, 패키지 스크립트, 테스트 로그, 최근 실패한 에이전트 작업, 저장소 구조, 코드 검토 체크리스트 및 PR 템플릿.
작업흐름:
- EasyClaw은 AGENTS.md, 스크립트, 로그 및 저장소 메모를 구성합니다.
- 저장소 컨텍스트 에이전트는 오래되었거나 모호한 지침을 식별합니다.
- 테스트 에이전트는 테스트 명령이 패키지 스크립트와 일치하는지 확인합니다.
- 보안 검토 에이전트는 비밀, 인증 및 프로덕션 구성에 대한 경계를 확인합니다.
- 문서 에이전트는 더 엄격한 AGENTS.md 개정 초안을 작성합니다.
- 검토 담당자는 불확실한 항목에 사람의 검토를 요청합니다.
- EasyClaw은 개선 노트, 수정된 템플릿 및 팀 요약을 패키지로 제공합니다.
- 개발자는 최종 파일을 검토하고 커밋합니다.
출력: 향상된 AGENTS.md 초안, 오래된 지침 목록, 누락된 테스트 명령 메모, 보안 경계 제안, PR 준비 요약 및 사람 승인 체크리스트.
이는 EasyClaw을 자동으로 수정하는 것이 아니라 더 나은 코딩 에이전트 컨텍스트를 유지하기 위한 구조화된 워크플로우입니다.
AGENTS.md 대 EasyClaw 워크플로
| 일 | AGENTS.md | EasyClaw 워크플로우 |
|---|---|---|
| 저장소 지침을 저장합니다. | 예 | 정리하고 검토하는 데 도움이 될 수 있습니다. |
| 설정 및 테스트 명령에 대해 설명합니다. | 예 | 명령을 작업 흐름으로 패키지화하는 데 도움이 될 수 있습니다. |
| 코딩 경계를 정의합니다. | 예 | 검토 중에 경계를 드러낼 수 있음 |
| 테스트를 실행하거나 로그를 읽습니다. | 아니요 | 실패한 로그 분석을 구성하는 데 도움이 될 수 있습니다. |
| 다중 상담원 역할 조정 | 아니요 | 역할 기반 워크플로를 지원할 수 있습니다. |
| 팀 요약을 보냅니다. | 아니요 | Slack / Discord / Teams 지원 업데이트를 준비할 수 있습니다. |
| Runs scheduled 리뷰 | 아니요 | 반복 요약을 지원할 수 있습니다. |
| 코드 승인 | 아니요 | 아니요; human 검토자가 결정 |
AGENTS.md은 컨텍스트 계층입니다. EasyClaw은 컨텍스트, 실행, 검토 및 전달을 중심으로 한 워크플로 계층입니다.
일반적인 AGENTS.md 실수
가장 흔한 실수는 파일을 너무 길게 만드는 것입니다. 다른 실수로는 모호한 규칙, 깨진 명령, 오래된 폴더 설명, 충돌하는 규칙, 누락된 보안 경계, 테스트 지침 없음, 완료 정의 없음, 사람의 검토를 피하기 위한 방법으로 AGENTS.md을 취급하는 것 등이 있습니다.
마지막 생각
AGENTS.md 모범 사례는 가능한 가장 긴 지침 파일을 작성하는 것이 아닙니다. 이는 AI 코딩 에이전트가 안전하고 효과적으로 작업하는 데 필요한 최소한의 유용한 저장소 컨텍스트를 제공하는 것입니다.
좋은 AGENTS.md은 설정, 테스트, 구조, 규칙, 작업 흐름, 경계 및 완료 정의를 설명합니다.
EasyClaw은 다음 레이어에 적합합니다. AGENTS.md, 코딩 에이전트, CI/CD 또는 코드 검토를 대체하지 않습니다. 개발자는 다중 에이전트 공동 작업, 예약된 보고서, 채팅으로 실행되는 명령, RPA 스타일 데스크톱 지원 및 사람이 검토한 결과물을 통해 저장소 지침을 가시적이고 반복 가능한 AI 코딩 워크플로로 전환하는 데 도움이 됩니다.
AGENTS.md은 AI 코딩 에이전트에 컨텍스트를 제공합니다. EasyClaw은 해당 컨텍스트를 안정적인 개발 워크플로우로 전환하는 데 도움이 됩니다.
자주 묻는 질문
AGENTS.md 워크플로우를 위해 EasyClaw를 사용해 보세요
팀이 Codex, Copilot, Cursor, Claude Code 또는 기타 AI 코딩 에이전트에 AGENTS.md을 사용하기 시작하는 경우 컨텍스트 파일에서 멈추지 마십시오. EasyClaw을 사용하여 해당 저장소 지침을 반복 가능한 AI 코딩 워크플로(정리된 컨텍스트, 다중 에이전트 검토, 실패한 로그 분석, 예약된 엔지니어링 보고서, PR 요약 및 인간 참여형 핸드오프)로 전환하세요.