agents-md-starter은(는) 무엇을 하나요?
출력: 리포지토리 루트에 AGENTS.md를 단일 진실 공급원으로 생성하고, @AGENTS.md를 포함하는 CLAUDE.md를 생성합니다 (Claude Code는 CLAUDE.md를 읽고 @path 임포트를 지원합니다). 파일 내 모든 명령어는 실제로 성공적으로 실행되었거나 명확히 미검증으로 표시되어야 합니다.
1단계 — 스캔
python3 scripts/scan_repo.py /path/to/repo # 사람 요약
python3 scripts/scan_repo.py /path/to/repo --json # JSON 형식의 사실
python3 scripts/scan_repo.py /path/to/repo --draft > AGENTS.draft.md # 템플릿 채우기
다음을 감지합니다: 파일 수 기준 언어, 잠금 파일 기반 패키지 매니저, package.json 스크립트, Makefile 타겟, pyproject.toml 도구 (pytest, ruff, mypy, uv/poetry), Go/Rust/Java 빌드 파일, 프레임워크 (Next.js, Astro, Vite, Django, FastAPI, Rails…), 모노레포 워크스페이스, CI 워크플로우, 환경 변수 예제 파일, 기존 에이전트 규칙 파일. 리포지토리 코드는 절대 실행하지 않습니다.
2단계 — 읽기 전에 쓰지 않기
- 발견된 모든 기존 규칙 파일 (
CLAUDE.md,.cursorrules,.cursor/rules/*.mdc,.github/copilot-instructions.md,GEMINI.md,CONTRIBUTING.md)을 읽습니다. 실제 규칙은 유지하고, 병합 및 중복 제거하며, 일반적인 규칙("깔끔한 코드 작성")은 제거합니다. - CI 워크플로우를 읽습니다: CI가 실행하는 명령어가 "테스트 통과"의 가장 신뢰할 수 있는 정의입니다.
- 대표적인 소스 파일 2~3개를 훑어보며 실제 규칙(명명 규칙, 오류 처리, 임포트 스타일)을 파악합니다 — 코드가 따르지 않는 규칙을 만들어내지 마십시오.
3단계 — 명령어 검증
초안에서 install/build/test/lint 명령어를 실행합니다 (안전하게: 배포 금지, 실제 데이터베이스에 대한 마이그레이션 금지, 게시 금지). 각 명령어에 대해: 정상 작동하면 유지; 올바른 변형이 명확하면 수정; 그렇지 않으면 (unverified)라고 표시하고 사용자에게 알립니다. 테스트 스위트가 느린 경우 시간을 기록합니다.
4단계 — AGENTS.md 작성
assets/AGENTS.template.md에서 시작합니다. 좋은 콘텐츠 규칙:
- 간결하게. 약 150줄 미만을 목표로 합니다. 에이전트는 모든 작업에서 이 파일을 읽으며, 모든 줄이 컨텍스트 비용을 발생시킵니다.
- 구체적이고 확인 가능하게: "커밋 전에
pnpm test --filter web실행"이 "코드를 테스트하세요"보다 낫습니다. - 명령어를 먼저 배치합니다. 그 다음 레이아웃, 규칙, 주의사항, "하지 말아야 할" 규칙을 배치합니다.
- 명확하지 않은 내용을 기록합니다: 편집하지 말아야 할 생성된 파일, 테스트에 필요한 환경 변수, 로컬에서 건너뛰어야 할 느린 테스트 하나, 비밀이 절대 저장되어서는 안 되는 위치.
- 모노레포: 공유 규칙을 위한 루트 AGENTS.md + 패키지별 명령어를 위한
packages/x/AGENTS.md(지원하는 에이전트는 가장 가까운 파일을 읽습니다).
5단계 — 다른 도구 연결
- Claude Code:
assets/CLAUDE.template.md에서CLAUDE.md를 생성합니다 (@AGENTS.md포함). CLAUDE.md가 이미 존재하면 해당 규칙을 AGENTS.md로 이동하고, 가져오기 아래에 Claude 전용 메모를 남깁니다. - Codex: 기본적으로
AGENTS.md를 읽습니다 — 다른 조치 불필요. - Cursor: 루트의
AGENTS.md를 읽습니다;.cursorrules콘텐츠를 AGENTS.md로 마이그레이션하고, 사용자 동의 후.cursorrules를 삭제합니다 (비권장)..cursor/rules/*.mdc는 글로벌 범위 규칙에만 유지합니다. - Gemini CLI: 기본적으로
GEMINI.md를 읽습니다;.gemini/settings.json에서"context": {"fileName": ["AGENTS.md", "GEMINI.md"]}를 설정하거나 AGENTS.md를 가리키는 한 줄짜리 GEMINI.md를 생성합니다. 설치된 버전의 문서에서 이 키가 이동되었는지 확인합니다. - 심볼릭 링크 (
ln -s AGENTS.md CLAUDE.md)도 작동하지만core.symlinks없이 Windows 체크아웃에서 깨집니다; 임포트 방식이 더 안전합니다.
각 도구가 읽는 파일에 대한 자세한 내용은 references/tool-support.md를 참조하십시오.
6단계 — 보고
다음을 나열합니다: 생성/변경된 파일, 검증된 명령어 (결과 포함), 미검증으로 표시된 명령어, 중복 또는 일반 규칙으로 제거된 규칙, 사용자 결정이 필요한 사항 (예: .cursorrules 삭제?). 사용자가 요청하지 않는 한 커밋하지 마십시오.