에이전트에게 유용한 저장소 맥락을 제공하세요

현재 체크아웃 상태부터 확인하세요

에이전트는 어떤 저장소와 브랜치를 바꾸는지 알아야 합니다. 작업 디렉터리에 관련 없는 변경이 있는지도 알아야 합니다. 이 사실에 따라 안전하게 편집할 대상과 최종 diff의 해석이 달라집니다.

구현 전에 프로젝트 지침과 패키지 구성을 확인하도록 요청하세요. 다른 저장소에서 기억한 명령이 여기서는 틀릴 수 있습니다. 익숙한 프레임워크 이름만으로 설치 버전이나 프로젝트 규칙을 알 수는 없습니다.

작은 변경에는 관련 모듈, 호출 코드, 테스트, 아키텍처 결정을 제공하세요. 조사 중 구체적인 필요가 드러나면 정보를 추가하세요.

오래 유지할 규칙은 저장소 지침에 두세요

지침 파일에는 지원 명령, 모듈 경계, 검토 요구사항, 담당자의 결정이 필요한 작업을 설명할 수 있습니다. AGENTS.md 규약은 코딩 도구가 알아볼 수 있는 위치에 이 정보를 둡니다. 도구 지원과 지침 우선순위는 다를 수 있으므로 실제 동작을 확인하세요.

지속적인 프로젝트 규칙은 저장소에 두세요. 현재 작업은 작업 설명에 두세요. 지침 파일을 모든 대화의 기록이나 임시 계획 목록으로 만들지 마세요.

유용한 지침은 “라우트가 접근 동작을 바꾸면 인가 통합 테스트를 실행하세요”입니다. 모호한 지침은 “항상 보안에 주의하세요”입니다. 첫 번째는 검토자가 확인할 수 있는 조건과 행동을 정합니다.

지침을 코드와 대조하세요

명령, 디렉터리, 아키텍처가 바뀌면 지침이 오래될 수 있습니다. 가이드가 존재하지 않는 스크립트를 가리키면 패키지 구성을 살펴보세요. 문서가 서비스를 읽기 전용이라고 설명하면 그 주장을 믿기 전에 권한을 확인하세요.

충돌을 기록하세요. 현재 버전의 직접적인 증거로 구현 동작을 이해하세요. 오래된 코드가 의도적인 정책을 위반한다고 정책을 조용히 버리지 마세요. 정책과 현재 동작은 서로 다른 질문에 답합니다.

예를 들어 가이드는 공유 브랜치에 직접 쓰기를 금지하지만 오래된 스크립트는 여전히 직접 쓸 수 있습니다. 올바른 대응은 정책을 유지하고 스크립트를 고치는 것입니다. 기존 코드가 있다고 금지된 작업을 반복할 권한이 생기지는 않습니다.

관련성 있고 안전한 맥락을 유지하세요

저장소 전체에는 자격 증명, 비공개 테스트 데이터, 고객 내보내기 파일, 오래된 지원 로그가 있을 수 있습니다. 저장소 접근이 허용되어도 모든 파일이 모델 서비스에 적합한 것은 아닙니다.

승인된 도구와 데이터 처리 규칙을 사용하세요. 맥락에서 비밀 정보를 제외하세요. 가능하면 고객 예시를 가상 데이터로 바꾸세요. 업로드한 파일뿐 아니라 연결된 도구도 확인하세요. 검색 커넥터는 최초 프롬프트에 없던 정보를 가져올 수 있습니다.

“비밀 정보를 읽지 마세요”라는 저장소 지침은 유용합니다. 하지만 비밀 정보 저장소와 민감한 디렉터리의 접근 제한을 대신하지는 못합니다.

다음 사람에게 유용한 기록을 남기세요

완료 시 풀 리퀘스트에 달라진 동작, 검증, 해결되지 않은 한계를 기록하세요. 지원되는 작업 흐름이 바뀌면 지속적으로 사용하는 프로젝트 문서를 갱신하세요. 에이전트 대화 전체를 저장소에 복사하지 마세요.

미래의 유지보수 담당자가 긴 대화를 재구성하지 않고도 작업을 반복할 수 있어야 합니다. 공식 기준 문서에 연결하고 각 규칙의 권위 있는 설명은 하나로 유지하세요.

좋은 맥락은 반복 조사를 줄입니다. 기대 동작과 작동하는 명령이 명확하므로 실수를 찾기도 쉬워집니다.