AI 에이전트가 오픈 소스 라이브러리를 찾고, 신뢰하고, 사용하며 사랑하게 만드는 방법

실제 레포지토리를 사례 연구로 활용한 실용적인 체크리스트

점점 더 많은 개발자들이 검색 엔진에 질문하기 전에 AI 에이전트에게 질문합니다. 만약 그들이 "Markdown에서 링크를 추출하는 데 좋은 라이브러리가 뭐야?"라는 질문을 한다면, 구글(Google)에 가는 것만큼이나 코딩 어시스턴트에게 갈 가능성이 높습니다.

에이전트가 프로젝트 내부에 들어가면, 의존성을 선택하고, 문서를 읽고, API를 기반으로 코드를 작성합니다. 이때 인간이 README 파일을 열어보지 않는 경우가 많습니다. 따라서 OSS(Open Source Software) 유지 관리자들에게 던져진 새로운 질문은 '프로젝트를 에이전트가 이해하기 쉽게 만드는 방법'입니다.

저는 작은 실제 프로젝트를 사례 연구로 사용하겠습니다: markdown-regex

이는 Markdown 파싱을 위한 준비된 RegExp 상수들을 제공하는, 의존성이 없는 TypeScript 라이브러리입니다. 이 라이브러리는 명확한 설치 섹션, API 테이블, TypeScript 타입, 듀얼 ESM/CommonJS 빌드, 그리고 여러 Node 버전에서의 CI(Continuous Integration)를 갖춘 견고한 기반을 가지고 있습니다. 또한 별점 약 11개를 보유하고 있어, 대부분의 사람들과 에이전트들이 접하지 못할 만한 유용한 프로젝트의 좋은 예시가 됩니다.

에이전트는 두 가지 방식으로 귀하의 프로젝트와 상호 작용하며, 각각은 다른 작업이 필요합니다. 첫 번째 방식은 추천 여부를 결정하기 위해 텍스트(검색 결과, 레지스트리 페이지, 문서)를 검색하는 것입니다. 두 번째 방식은 리포지토리를 읽고 API를 호출하여 작업을 완료하는 것입니다. 이 글의 나머지 부분에서는 이 두 가지 방식을 모두 다루며, 각 방식에 영향을 미치는 신뢰 지표들(trust signals)도 함께 다룹니다.

파트 1: 발견 가능하고 추천받을 수 있게 만들기 (Be findable and recommendable)

언제 사용해야 하고, 언제 사용하지 말아야 하는지 명시하기

라이브러리를 선택하는 에이전트는 의사 결정 규칙(decision rule)이 필요합니다. 대부분의 README는 프로젝트가 무엇을 하는지에 대해서만 설명할 뿐, 그것이 언제 적절한 선택인지는 절대 언급하지 않습니다.

정규식 기반 Markdown 툴킷의 경우, 이는 다음과 같이 명확하게 말해야 함을 의미합니다: "빠른 추출, linting(린팅), 경량 변환에 사용하세요. 만약 실제 AST(추상 구문 트리)나 깊게 중첩된 구조, 또는 엄격한 CommonMark 준수가 필요하다면 remark나 markdown-it 같은 전체 파서를 사용하세요." 이러한 정직함은 두 가지 방식으로 도움을 줍니다. 에이전트는 당신이 잘하는 일에 대해 추천하고, 당신이 실패할 만한 일에 대해서는 추천을 중단함으로써 당신의 평판을 보호해 줍니다.

실제 검색 쿼리와 일치하는 설명 및 주제 작성하기

현재 저장소의 태그라인은 "Markdown 콘텐츠를 파싱하는 데 도움이 되는 상수 세트"입니다. 정확하지만 모호합니다. 다음을 비교해 보세요:

마크다운에서 헤더, 링크, 이미지, 목록, 코드 등을 추출하기 위한 의존성 제로(Zero-dependency), TypeScript 타입 지정 RegExp 패턴.

두 번째 버전은 사람들이 검색하는 명사들을 포함하고 있습니다. 저장소 주제도 마찬가지입니다. 이 프로젝트는 javascript, markdown, npm, regex, 그리고 rollup을 나열합니다. 하지만 마크다운 추출기가 필요할 때 아무도 "rollup"을 검색하지 않습니다. 더 나은 후보로는 typescript, markdown-parser, regexp, zero-dependency, 그리고 commonmark이 있습니다.

태그가 지정된 릴리스를 배포하고 모든 표면을 일관되게 유지하기

GitHub 페이지에 릴리스나 패키지가 없으면, 에이전트(그리고 사람)는 어떤 버전이 최신인지 또는 무엇이 변경되었는지 쉽게 알 수 없습니다. 버전을 태그로 지정하고 릴리스 노트를 게시하세요. 베타 버전이나 대대적인 수정 중이라면 명확하게 밝히고 마이그레이션 경로를 문서화해야 합니다. 그렇지 않으면 에이전트들이 오래된 튜토리얼의 구식 사용법을 계속 제안할 것입니다.

GitHub, npm, 그리고 프로젝트에 관한 모든 아티클에서 이름, 설명, README 내용을 일관되게 유지하세요. 도구가 찾을 수 있도록 관례적인 README.md 케이싱을 사용하세요.

파트 2: 에이전트가 실제로 읽는 파일을 제공하기

AGENTS.md 추가하기

AGENTS.md는 떠오르는 컨벤션입니다. 이는 저장소 루트에 있는 일반 Markdown 파일로, 코딩 에이전트에게 프로젝트에서 어떻게 작업해야 하는지 알려줍니다. 여러 도구가 이를 읽습니다. 다음 내용을 포함해야 합니다:

• 빌드(build), 테스트(test), 린팅(lint), 타입 체크(typecheck)를 위한 정확한 명령어
• 디렉토리 레이아웃과 각 위치에 무엇이 있는지
• 새로운 기능을 추가하는 방법 (이 라이브러리의 경우, RegExp와 그 테스트를 추가하는 방법)
• 컨벤션 및 피해야 할 사항들

맥락을 전혀 모르고 질문할 수 없는 기여자(contributor)를 위해 작성된 README라고 생각하세요. 도구별 커버리지를 원한다면, 작은 CLAUDE.md 또는 유사한 파일이 단순히 이를 가리키기만 하면 됩니다.

llms.txt 고려하기

llms.txt

is a proposed convention for a concise, link-based summary of a project designed for language models, optionally accompanied by a longer llms-full.txt

containing the complete API. Support among crawlers and agents is still uneven, so treat it as a cheap bet, not a guaranteed win. It costs almost nothing to produce and can be generated from your existing docs.

에이전트가 이미 있는 곳에 문서를 배치하세요: 타입(types)

라이브러리를 사용하여 코드를 작성하는 에이전트는 README를 보기 훨씬 전에 .d.ts 파일을 보고 편집기 툴팁을 보게 됩니다. 모든 내보내기 항목(export)에 대한 JSDoc 주석은 아마도 이용 가능한 단일 최고 레버리지 개선 사항일 것입니다. 각 주석에는 한 줄 설명, 일치하는 예제, 그리고 이상적으로는 일치하지 않는 예제를 포함해야 합니다.

ts

/**
* Matches Markdown links: `[text](url)`.
* Capture groups: 1 = link text, 2 = URL.
...

(위의 정규 표현식 본문은 자리 표시자이며, 핵심은 문서의 형태입니다.)

파트 3: API를 자체적으로 설명 가능하게 만들기

REGEXP_LINK — 링크 구문 — 은 [text](url)와 일치한다고 적힌 표는 독자에게 상수가 무엇을 위한 것인지 알려주지만, 어떻게 작동하는지는 알려주지 않습니다. 에이전트(그리고 사람)는 행동적 세부 사항이 필요합니다. 모든 내보내기 항목에 대해 다음을 문서화하세요:

캡처 그룹(Capture groups). 각 그룹은 무엇을 포함합니까? 링크 패턴의 경우, [text, url]입니까?
플래그(Flags). g 플래그가 설정되어 있습니까? 전역 정규 표현식(Global regexes)은 lastIndex 상태를 가지며, 이를 호출 간에 재사용하는 것은 간헐적 버그의 고전적인 원인입니다. 상수가 전역이라면, 안전하게 사용하는 방법을 알려주세요.알려진 실패 모드(Known failure modes). 중첩 강조 표시, 코드 스팬 내부 링크, 단어 중간 밑줄 등. 정규 표현식 기반 파싱에는 한계가 있으며, 이를 문서화하면 에이전트가 조용히 깨지는 코드를 생성하는 것을 방지할 수 있습니다.실제 입력 및 출력(Real input and output). 실제 반환되는 배열을 보여주는 복사-붙여넣기 예제가 설명 문단보다 더 가치가 있습니다.

공개 인터페이스에서 관심사를 분리하기

markdown-regex

하나의 테이블에 두 가지 종류의 내보내기(export) 패턴을 혼합합니다: Markdown 구문을 일치시키는 패턴과 </ul><ul>와 같이 생성된 HTML에서 작동하는 정리(cleanup) 패턴입니다.

이들을 섞어 쓰면 라이브러리가 무엇인지 모호해집니다. 문서에 그룹화하거나, 서브 경로 내보내기(subpath export)로 정리 도우미(cleanup helpers)를 노출하면 사람과 모델 모두에게 더 명확한 정신적 모델을 제공합니다.

고수준 진입점 (High-level entry point) 제공하기

순수 정규식(raw regexes)은 모든 사용자(consumer)가 자신만의 로직을 구성하도록 강요합니다. extractLinks(md)와 같이 타입이 지정된 객체를 반환하는 몇 가지 도우미 함수는 에이전트가 오류의 여지가 훨씬 적은 한 줄로 일반적인 경우를 해결할 수 있게 합니다. 에이전트는 명백한 호출이 올바른 결과를 산출하는 API를 선호합니다.

파트 4: 방치 신호 제거하기 (Remove signals of neglect)

에이전트와 인간 모두 의존성(dependency)을 신뢰할지 결정할 때 유지보수 신호를 고려합니다. 이 저장소에서는 몇 가지 쉽게 수정할 수 있는 부분이 눈에 띕니다:

• 루트 디렉터리에 있는 불필요한 파일, source-fullcodetest.md는 남은 스크래치 작업처럼 보입니다. - 두 개의 Jest 설정 파일 (jest.config.js와 jest.config.cjs)은 미완료된 마이그레이션을 암시합니다. - 가시적인 분류(triage)가 없는 열린 이슈 17개와 풀 리퀘스트 2개는 프로젝트가 실제로는 활발함에도 불구하고 방치된 것처럼 보이게 합니다. 오래된 것을 닫고, 일부를 good first issue로 라벨링하며, 기여자(contributor), 인간이든 자동화되었든 간에 명확한 진입 경로를 제공해야 합니다. - npm 버전, CI 상태, 번들 크기, 커버리지에 대한 배지(Badges)는 많은 신뢰 정보를 한눈에 압축합니다.

• SECURITY.md 파일은 도움이 됩니다. 특히 정규식 라이브러리의 경우, ReDoS (치명적 백트래킹, catastrophic backtracking)가 명백한 관심사이므로 CI에서 safe-regex나 recheck와 같은 검사기를 실행하고 README에 이를 명시해야 합니다.

파트 5: 기계가 읽을 수 있는 증거 제공하기 (Provide machine-readable proof)

주장은 약하지만, 증거는 강력합니다. 세 가지 종류의 증거가 도움이 됩니다:

피처 기반 테스트(Fixture-driven tests). 모든 패턴에 일치하는 예시와 일치하지 않는 예시를 담은 테이블입니다. 에이전트는 테스트에서 의도된 동작을 추론하며, 이 테이블은 동시에 문서 역할도 합니다.실행 가능한 examples/

폴더 내에 사용 사례별로 하나의 파일을 두고 README에서 연결합니다.간단한 추출 작업에 대한 경량 대안과의 벤치마크 또는 비교가 필요합니다. 구체적인 수치는 에이전트가 귀하를 추천할 때 인용할 특정 근거를 제공합니다.

파트 6: 모델들이 학습하는 곳에 배포하기

모델과 검색 시스템은 여러 독립적인 장소에서 나타나는 것을 표면화합니다. npm 페이지를 최신 상태로 유지하세요. 주요 버전이 출시될 때마다 프로젝트에 대한 오래된 아티클을 업데이트해야 합니다. 그렇지 않으면 구식 튜토리얼이 에이전트에게 쓸모없는 API를 가르치기 때문입니다.

귀하의 라이브러리를 사용하는 'JavaScript에서 Markdown에서 링크나 헤더 추출 방법'과 같은 짧은 가이드를 게시하세요. 엄선된 'awesome' 리스트에 등재되고, 관련 프로젝트 간에 연결하여 서로 강화되도록 하세요.

만약 하루 오후 시간만 있다면 (또는 Joyner Lucas가 말했듯이 - “살 시간이 24시간 남았다면 어디로 가겠느냐?”)

다음 여섯 가지를 순서대로 수행하세요:

• 저장소 설명(repository description)과 토픽을 재작성합니다.
• AGENTS.md 파일을 추가합니다.
• 모든 내보내기(export)에 예시와 함께 JSDoc을 추가합니다.
• 문서에서 클린업 헬퍼를 핵심 Markdown 패턴과 분리합니다.
• README에 '사용해야 할 경우 / 사용하지 말아야 할 경우' 섹션을 추가합니다.
• 태그가 지정된 릴리스(tagged release)를 게시합니다.

이것들을 함께 수행하면 최소한의 노력으로 발견 가능성, 저장소 내 사용 용이성, 그리고 신뢰도를 모두 확보할 수 있습니다.

핵심 요약

프로젝트를 에이전트 친화적으로 만드는 데 특별한 트릭이 필요하지 않습니다. 여기에 있는 거의 모든 것은 좋은 문서와 좋은 유지보수 활동이 이미 갖추고 있는 것이며, 단지 더 명시적이고 구조화된 형태일 뿐입니다. 에이전트는 줄 사이의 내용을 훑어보거나, 관리자에게 질문을 하거나, 오래된 README를 용서할 수 없습니다.

프로젝트가 무엇을 위한 것인지 명시하고, 어떻게 작동하는지를 정확하게 보여주며, 저장소를 눈에 띄게 관리하고 있다면, 에이전트와 그에 의존하는 개발자 모두 귀하를 선택하기 더 쉽게 느낄 것입니다.