Your contributors are AI-first now. Is your project?

개요

AutoGPT의 AI 엔지니어 Nicholas Tindle은 AI 에이전트가 작성한 Pull Request(PR)가 증가하는 상황에 대응하여, 프로젝트의 통제권을 유지하면서 AI 기여를 효과적으로 활용하기 위한 실질적인 방법들을 제시합니다.

주요 내용

* AI 기여자 관리의 필요성: AI 에이전트가 작성한 PR이 증가함에 따라, 기존 프로젝트 관리 방식으로는 이를 효과적으로 관리하기 어려워지고 있습니다.
* 문서화 위치의 중요성: AI 에이전트는 스스로 문서를 찾아 읽지 않으므로, 에이전트가 작업을 수행하는 디렉토리 내에 관련 지침(예: AGENTS.md)을 배치해야 합니다.
* 에이전트별 특화 지침: Claude와 같은 특정 AI 모델이 PR을 생성할 때 저장소별 컨텍스트가 부족한 문제를 해결하기 위해 CLAUDE.md와 같은 파일에 지침을 명시했습니다.
* 중앙화된 AGENTS.md: Claude 파일이 Copilot이나 Codex와 같은 다른 에이전트에 의해 무시되는 문제를 해결하기 위해, AGENTS.md 파일을 중앙화하고 기존 파일들이 이 파일을 참조하도록 구성했습니다.
* 디렉토리별 스코프: AGENTS.md 파일은 특정 디렉토리에 국한되어 관리되며, 스킬(skill)은 저장소 외부에서도 발견될 수 있습니다.
* 프로젝트별 스킬 개발: 프론트엔드 엔지니어는 특정 폴더에 컴포넌트가 있는 경우 Storybook 테스트를 작성하는 지침을 스킬 형태로 개발하여 자동화했습니다.
* 실효성 있는 게이트(Gates) 구현:
* PR 템플릿 강제: PR 템플릿을 따르지 않는 PR은 자동으로 닫히도록 설정하여 에이전트 행동을 변화시켰습니다.
* 테스트 계획의 트리거: PR 템플릿에 테스트 계획 작성을 요구하고, "Pull Request 테스트"라는 문구를 트리거로 사용하여 PR 테스트를 자동 실행하도록 했습니다.
* CI를 제안이 아닌 필수 사항으로: Codecov 커버리지 임계값을 필수 확인 사항으로 설정하여 에이전트가 스스로 테스트를 작성하도록 유도했습니다.
* CLA를 인간 감지 도구로 활용: CLA 서명은 브라우저와 GitHub OAuth 흐름을 요구하여 현재 에이전트에게는 어렵기 때문에, 인간 기여자를 식별하는 수단으로 사용합니다.
* 리뷰 스레드 해결 전 커밋 SHA 요구: 일부 에이전트가 코드를 수정하지 않고 리뷰 스레드를 해결하는 것을 방지하기 위해, PR 주소 지정 스킬을 사용하여 수정 후 커밋하고 해당 커밋 SHA를 링크하도록 했습니다.
* 제거된 게이트: CI 실패 시 에이전트가 실패 원인을 분석하고 주석을 다는 기능은 정보 과부하를 유발하여 제거했습니다.
* 주의 사항:
* 잘못 작성된 AGENTS.md 파일은 오히려 컨텍스트를 오염시킬 수 있습니다.
* GraphQL API는 CLI 사용량이 많을 경우 속도 제한에 걸릴 수 있으므로 GitHub App 인증을 사용해야 합니다.
* 고도화된 PR 테스트 도구는 비용이 많이 들므로, 전체적인 스택에 대한 실행 빈도를 조절해야 합니다.
* 더 이상 사용하지 않는 GitHub 앱은 권한을 해제하여 보안을 강화해야 합니다.
* 모든 것이 게이트는 아니다:
* 모든 PR을 수락할 필요는 없으며, LLM 출력물을 병합하는 것은 유지보수 부담이 영구적으로 발생합니다. PR을 닫고 직접 수정하는 것도 유효한 선택지입니다.
* PR을 닫고 직접 수정할 경우, 기여자가 기여한 부분을 인정하여 공동 저자로 추가하는 것이 좋습니다.
* 오픈 소스 협업의 진화: 라이선스, 이슈, PR에 이어 리포지토리 내의 명시적인 지침이 협업을 더욱 명확하게 만드는 단계로 나아가고 있습니다.

시사점

AI 에이전트가 기여자로 참여하는 시대에, 프로젝트 관리자는 AI의 특성을 이해하고 저장소 내에 지침을 배치하며 자동화된 게이트를 설정함으로써 프로젝트의 품질과 관리 효율성을 유지할 수 있습니다.