AGENTS.md는 얼마나 흔할까요? GitHub 표본 조사에서 활성 저장소 6.2%, 전체 공개 저장소 1.0%

AI 요약

AGENTS.md가 개발 현장에서 얼마나 쓰이는지 알려면, 파일이 있는 저장소만 모아 비율을 계산해서는 안 됩니다. 글쓴이는 앞선 조사에서 이미 AGENTS.md가 존재하는 저장소를 분모로 삼았고, 그 결과로는 GitHub 전체에서 얼마나 흔한지 답할 수 없다는 점을 인정합니다. 이번에는 파일 유무와 독립적으로 저장소를 뽑는 표본을 구성해 두 가지 비율을 측정합니다. 최근 90일 안에 푸시된 활성 저장소 817곳 중 51곳, 즉 6.2%에 AGENTS.md가 있습니다. 95% 신뢰구간은 4.8~8.1%입니다. 전체 공개 저장소 표본 924곳에서는 9곳, 1.0%였고 신뢰구간은 0.5~1.8%입니다. 같은 파일을 세어도 어떤 저장소를 모집단으로 삼느냐에 따라 수치가 여섯 배 차이 납니다.

무엇을 분모로 삼느냐가 답을 바꿉니다

활성 비율은 “현재 작업하는 프로젝트에서 이 관행을 얼마나 볼 수 있나”에 답합니다. 전체 공개 저장소 비율은 “GitHub에 공개된 저장소 중 얼마나 보유하고 있나”를 보여줍니다. 글쓴이는 두 모집단을 섞으면 자신 있게 잘못된 결론을 내리기 쉽다고 설명합니다. 공개 저장소의 93%는 최근 90일 동안 푸시되지 않았고, 29%는 포크이며, 8.3%는 비어 있습니다. 전체 저장소 모집단에는 오랫동안 방치된 저장소가 많아 활성 저장소보다 비율이 낮게 나옵니다. 실제로 전체 표본에서 발견한 AGENTS.md 9개 가운데 7개는 3개월 넘게 푸시되지 않은 저장소에 있었습니다.

글쓴이는 결과를 보기 전에 해석 기준도 정합니다. 1% 미만이면 얼리 어답터의 호기심거리, 1~5%면 ‘초기 단계지만 측정 가능한 관행’, 10% 초과면 표준 관행으로 부르겠다는 기준입니다. 활성 저장소 비율은 중간 구간보다 약간 높지만, 표준이라고 부를 수준은 아닙니다. 따라서 AGENTS.md는 활성 프로젝트에서 실제로 쓰이지만, 공개 저장소 전반의 관행은 아닙니다.

표본은 서로 다른 방식으로 뽑았습니다

활성 저장소 표본은 생성 연도별로 시간 구간을 정하고, GitHub 검색 결과를 모두 받은 뒤 구간마다 무작위로 50개를 추렸습니다. 검색 결과 첫 페이지는 인기나 활동성에 따라 정렬되므로 그대로 쓰면 편향이 생깁니다. 2026년처럼 검색 결과가 1,000개 제한을 넘는 구간은 날짜와 시간을 더 좁혀 표본을 뽑았습니다. 활성 조건은 최근 90일 안에 푸시됐고, 포크나 보관된 저장소가 아닌 경우입니다.

전체 공개 저장소는 GitHub 검색으로 무작위 표본을 만들 수 없었습니다. 검색 결과에 무작위 정렬 기능이 없고 별이나 활동량이 높은 저장소가 우선되기 때문입니다. 대신 저장소 ID 범위에서 ID를 균등하게 뽑아 API로 조회했습니다. 현재 최대 ID를 이진 탐색으로 찾은 뒤 ID를 추출했으며, 그중 실제 공개 저장소인 비율은 35%였습니다. 쓸 수 있는 표본 1,000개를 얻으려면 2,920번 조회해야 했습니다. 전체 조사에는 약 1,900개 저장소가 쓰였고 응답은 모두 캐시했습니다.

두 표본 모두 저장소마다 GET /repos/{owner}/{repo}/git/trees/HEAD?recursive=1을 한 번 호출하고, 경로에서 파일명을 대소문자 구분 없이 찾았습니다. 재귀 조회를 해야 docs/AGENTS.md 같은 하위 경로도 잡을 수 있습니다. 활성 표본에서 CLAUDE.md는 5.4%였고, AGENTS.md와 통계적으로 구별되지 않았습니다. 두 파일이 모두 있는 저장소는 18곳, CLAUDE.md만 있는 곳은 26곳이었습니다. 따라서 AGENTS.md만 확인하면 활성 표본에서 에이전트 지침 파일을 둔 저장소를 상당수 놓칩니다. GitHub Copilot 지침 파일은 1.1%, Cursor 규칙 파일은 0.7%였습니다.

채택 추세와 효과는 아직 답하지 못했습니다

생성 연도별로 나눈 표본에서 2026년 저장소의 비율은 2022년 이전 저장소의 0.67배였습니다. 하지만 이를 두고 채택이 줄거나 정체됐다고 결론 내릴 수는 없습니다. 생성 연도와 저장소 나이가 뒤섞여 있기 때문입니다. 2010년에 만들어져 2026년에도 푸시되는 저장소는 오래 살아남으며 규칙을 축적했을 수 있지만, 2026년 저장소는 첫 주말에 만든 프로젝트일 수 있습니다. 파일이 언제 추가됐는지 커밋 이력을 조사하지 않았으므로 채택 추세는 측정하지 않았다고 밝힙니다.

파일의 존재가 작업 효과를 보장하지도 않습니다. 글쓴이는 AGENTS.md가 있는 저장소가 더 나은 결과를 내는지 확인하려면 통제된 작업과 블라인드 평가, 효과 크기 측정이 필요하다고 봅니다. 제안한 실험은 세 집단을 비교합니다. 실제 지침 파일을 제공하는 집단, 문서를 주지 않는 집단, 같은 길이의 무관한 문서를 제공하는 집단입니다. 마지막 비교로 지침 자체의 효과와 단순히 컨텍스트를 더 제공한 효과를 나누려는 설계입니다. 글에서는 실험을 아직 실행하지 않았으며, 현재 수치는 모두 보급 현황을 설명할 뿐 효과를 입증하지 않는다고 선을 긋습니다.

커뮤니티 반응

• @raknaos — 앞선 두 글의 분모를 스스로 바로잡은 점이 가장 유용합니다. 분모를 고르는 일이 측정의 전부이고, 그 선택을 명시해야 막연한 인상과 측정을 구분할 수 있습니다. 6.2%와 1.0%는 활성 프로젝트와 공개 저장소 전체를 기준으로 삼을 때 각각 정직한 답이 나온다는 점을 보여줍니다. 다만 90일 안에 푸시된 저장소를 ‘활성’으로 정의하면, AGENTS.md를 관리하는 관행이 아니라 자동화 파이프라인이 최근에 실행된 저장소까지 포함될 수 있습니다. 조사 기간에 파일 자체가 바뀌었는지, 아니면 그저 존재했는지도 나눠 봤나요?
  • @janzong — 아직 나누지 않았습니다. 제안한 구분은 다음으로 살펴볼 만한 분석입니다. ‘활성’은 저장소 단위로 정의했습니다. 최근 90일 안에 푸시됐는지를 보며, 파일 검사는 현재 트리에서 재귀 조회 한 번으로 끝나므로 파일의 존재만 측정합니다. CI가 일주일에 여섯 번 푸시하는 저장소도, AGENTS.md를 처음 만들어 둔 뒤 한 번도 고치지 않은 저장소와 똑같이 집계됩니다. 전체 공개 저장소 표본의 AGENTS.md 발견 9건 중 7건이 최근 3개월 동안 푸시되지 않은 저장소에서 나왔습니다. 그래서 6.2%는 ‘관리되는 관행’의 비율이라기보다 상한에 가깝다고 봅니다. 파일을 마지막으로 수정한 커밋을 찾는 방식은 저장소마다 경로 필터를 적용한 커밋 조회 한 번이면 되므로, 비용도 크지 않습니다. 다만 봇이 파일을 다시 생성하는 경우도 잡히고, 오랫동안 고치지 않은 규칙 파일도 여전히 에이전트가 읽을 수 있습니다. 최근 수정과 실제 사용은 서로 다른 주장입니다.
• @anp2network — 이 비율을 확정하기 전에 확인할 만한 점이 하나 있습니다. 재귀 트리 API는 항목이 10만 개 또는 7MB 제한을 넘으면 결과를 자를 수 있습니다. 그래도 응답은 200으로 오고 truncated: true가 붙습니다. response["tree"]만 읽으면 AGENTS.md가 있는 저장소를 없는 것으로 셀 수 있습니다. 저장소 크기와 누락이 연관되므로 817개 표본에서 평균을 내도 사라지지 않습니다. 캐시된 응답에서 truncated가 참인 개수를 집계해 공개해 주세요. 하위 경로를 잡으려는 재귀 조회가, 잘림으로 같은 경로를 놓칠 수도 있습니다. 반대로 모든 경로에서 대소문자 구분 없이 찾으면 vendor/나 node_modules/의 의존성 파일을 세어 비율을 부풀릴 수도 있습니다.
  • @janzong — 확인 결과, 사용할 수 있는 트리 응답 1,742개 중 5개가 truncated: true였습니다. 활성 표본에서 3개, 전체 공개 표본에서 2개입니다. 잘린 응답에서 반환된 경로에는 AGENTS.md나 CLAUDE.md가 없었습니다. 다만 세 활성 저장소에 숨은 파일이 각각 하나씩 있다고 가정하면 활성 비율은 6.2~6.6%가 됩니다. 전체 비율도 최악의 경우 1.0~1.2%입니다. 활성 표본에서 발견한 AGENTS.md 51개 중 46개는 루트 파일이었습니다. 하위 경로에만 있던 다섯 건 가운데 하나는 vendor/ 아래의 의존성 파일이었고, 하나는 에이전트 지침이 아니라 블로그 글 content/posts/agents.md였습니다. 루트 파일만 세면 활성 표본은 5.6%, 전체 표본은 0.8%입니다. 앞으로 재귀 결과와 루트 파일 결과를 함께 공개하겠습니다.
• @frankchu — 앞선 두 글에서 쓴 분모를 스스로 버린 점이 이 조사를 믿게 합니다. 특히 전체 표본에서 AGENTS.md가 발견된 9개 중 7개가 석 달 넘게 갱신되지 않은 저장소에 있다는 점이 계속 마음에 남습니다. 제 에이전트가 매번 읽는 파일은 16,230자, 대략 3,281토큰이고 열 개 섹션 중 네 개는 제목에 날짜가 있습니다. 오래된 내용을 지우지 않고 계속 덧붙였기 때문입니다. 그중 낡은 한 줄 때문에 에이전트가 몇 달 전에 자동화한 수동 절차를 자신 있게 설명한 적도 있습니다. 활성 저장소 안에서 파일은 남아 있지만 내용이 죽은 상태와, 실제로 쓰이는 파일을 구분할 외부 신호가 있을까요?
  • @janzong — 파일 자체의 마지막 커밋 날짜를 저장소의 마지막 푸시 날짜와 비교하면 됩니다. 저희 데이터셋의 commit_date는 558개 행 모두에서 저장소의 최신 커밋 시각과 같았습니다. 파일의 수정 시각이 아니라 저장소 HEAD의 시각을 담고 있었던 것입니다. 그래서 AGENTS.md 경로의 파일 이력을 다시 조회했습니다. 최근 90일 안에 푸시된 저장소 523곳 중 262곳은 파일을 30일 넘게 수정하지 않았고, 113곳은 90일 넘게, 52곳은 180일 넘게 수정하지 않았습니다. 365일이 넘은 곳은 4곳입니다. 저장소가 90일 넘게 유휴 상태인 곳은 33곳이므로, 활성 저장소 안에서 오래된 파일을 둔 경우가 더 많습니다. 다만 이 수치는 검색으로 모은 기존 코퍼스에 한정됩니다.

원문: dev.to / 번역·요약: Trawling