vpd-permission-poc/AGENTS.md

문서 작성 공통 규칙

이 저장소에서 새 문서를 만들거나 기존 문서를 크게 고칠 때는 아래 구조를 기본으로 한다.

1. 첫 문서(README.md)는 독자가 2~3분 안에 목적, 범위, 결정사항, 전체 구성, 현재 상태를 파악하는 개요 문서로 작성한다.
2. README에는 복잡한 절차와 모든 오류 사례를 누적하지 않는다. 아래와 같이 역할별 상세 문서로 분리하고, 개요에서 명확한 링크를 제공한다.
   • architecture.md: 신뢰 경계, 컴포넌트 책임, 데이터·인증 흐름, 설계 결정
   • cookbook.md: 준비물, 단계별 적용 명령/화면값, 검증, 롤백
   • troubleshooting.md: 증상 → 원인 → 확인 방법 → 해결 → 재발 방지
   • 필요하면 operations.md, security.md, adr/ 등 목적이 드러나는 파일을 추가한다.
3. 그림은 한 장에 모든 세부사항을 넣지 않는다.
   • README에는 시스템 경계와 핵심 흐름만 보이는 개요도를 둔다.
   • 상세 연결·claim·포트·예외 흐름은 architecture 또는 cookbook의 상세도로 분리한다.
   • 각 그림 아래에는 독자가 알아야 할 결론을 한두 문장으로 적는다.
4. Cookbook은 실제 적용 순서를 따르며, 각 단계에 입력값의 출처, 성공 판정, 실패 시 연결할 troubleshooting 항목을 포함한다.
5. 비밀번호, client secret, access token, 개인 식별 정보는 어떤 문서·그림·명령 출력에도 기록하지 않는다. 위치와 안전한 조회/rotation 방법만 기록한다.
6. README의 문서 지도와 각 상세 문서의 상호 링크를 변경 후 반드시 확인한다.

문서의 독자는 운영자·개발자·검토자다. 제품명과 전문 용어는 필요할 때만 쓰고, 처음 한 번은 평이한 말로 역할을 정의한다.