auth.md

auth.md는 AI 에이전트가 GitHub·Slack·데이터베이스 같은 외부 서비스에 접속할 때 어떤 인증이 필요한지 적어 두는 마크다운 파일 협약이다. 작업 방식을 적는 CLAUDE.md와 달리 인증 방식, 자격증명 위치, 권한 범위를 맡고, 코드베이스 루트나 서비스 디렉터리에 두어 사람과 에이전트가 함께 읽는다.

아직 자리를 잡아 가는 신흥 협약이고, 에이전트용 파일 가운데 인증을 맡는다.

사람도 읽고 에이전트도 바로 쓴다

auth.md는 사람이 읽는 문서이면서, 에이전트가 읽고 곧바로 실행에 쓸 수 있는 구조로 쓴다. 막연한 설명보다 "이 API는 Bearer 토큰을 쓰고, 토큰은 GITHUB_TOKEN 환경 변수에서 읽는다"처럼 구체적으로 적는 게 핵심이다.

실제 키는 절대 넣지 않는다

auth.md에는 자격증명의 위치와 형식만 적는다. 실제 키는 지금처럼 .env 파일이나 시크릿 매니저에 두고, auth.md는 에이전트가 그 키를 어디서 찾아 어떻게 쓰는지만 안내한다.

에이전트 작업이 복잡할수록 쓸모가 커진다

에이전트가 코드베이스를 스스로 살피고 여러 서비스와 연결해 일할수록, 인증 정보를 한곳에 정리한 파일이 중요해진다. 작업 방식은 CLAUDE.md에, 인증은 auth.md에 나눠 적어 두면 에이전트가 외부 서비스와 더 안전하게 연동할 수 있다.

프로젝트를 열 때, 에이전트 여럿이 일할 때

Claude Code 같은 코딩 에이전트는 프로젝트를 처음 열 때 auth.md를 읽고, 어떤 외부 서비스에 어떤 권한으로 접근해야 하는지 따로 설명을 듣지 않아도 파악한다. 에이전트에게 일을 맡길 때마다 인증 방법을 다시 알려줄 필요가 없어진다.

여러 에이전트가 나눠 일하는 파이프라인에서도 쓸모가 크다. 한 에이전트는 GitHub API를 부르고 다른 에이전트는 Slack 알림을 보낸다면, 각각의 인증 방식과 환경 변수를 auth.md 한 곳에 적어 둔다. 그러면 모든 에이전트가 같은 인증 정보를 일관되게 공유한다.