사람과 AI 에이전트가 함께 읽고 이어가는, Git 기반 프로젝트 문서 구조 템플릿입니다.
작업 하나를 문서 하나로 관리합니다. 사람이 현재 상황과 판단 근거를 읽고 수정하면, 다음 에이전트도 같은 문서를 기준으로 작업을 이어갑니다. 문서는 한국어로 작성합니다.
.
├── AGENTS.md # 에이전트의 문서 읽기·작성 규칙
├── CLAUDE.md # Claude Code에서 공통 규칙 연결
└── docs/
├── README.md # 프로젝트 현황과 작업 목록: 여기서 시작
├── plan.md # 제품 목적, 사용자, 기능 범위, 제품 정책
├── architecture.md # 구성 요소, 폴더 책임, 의존 관계, 구조 규칙
├── specs.md # 기술 스택, 구현 규칙, 실행·검증 방법
├── design.md # (선택) UI 디자인 기준과 코드·화면 근거
├── work/
│ └── _template.md # 현재 상황 → 진행과 판단 → 남은 일
└── sessions/
└── _template.md # 필요한 경우에만 남기는 상세 세션 기록
사람은 docs/README.md의 작업 목록에서 필요한 문서로 이동합니다. 에이전트는 AGENTS.md의 규칙에 따라 같은 문서를 읽고 갱신합니다. docs/의 파일명과 구성은 이 템플릿의 약속입니다.
- 이 저장소의
AGENTS.md,CLAUDE.md,docs/를 대상 프로젝트에 가져옵니다. 같은 파일이 있으면 기존 내용을 보존하며 합칩니다. - 기존 README는 유지하고 문서 홈으로 가는 링크를 추가합니다. 이 README는 템플릿 사용 안내이므로 대상 프로젝트의 README를 대신하지 않습니다.
- 실제 코드와 사용자의 요구를 확인해
docs/plan.md,docs/architecture.md,docs/specs.md,docs/README.md의 빈칸을 채웁니다. 모르는 내용은미정또는미확인으로 남깁니다. - UI 디자인 기준이 필요한 프로젝트에서는 docs/design.md도 작성합니다. 스타일·토큰·공통 컴포넌트를 분석하고 가능하면 실제 화면을 함께 확인합니다. 관찰한 구현과 합의된 기준을 구분하고 원본 파일을 연결합니다. UI가 없거나 이 문서를 사용하지 않으면 가져오지 않아도 되며, 관련 안내와 링크도 함께 정리합니다.
- 필요하면 이 저장소의
.gitignore항목을 기존 파일에 합칩니다. 이후 작업은docs/work/에 기록합니다.
에이전트에게 다음처럼 요청해도 됩니다.
이 프로젝트에 docs-starter의 한국어 문서 구조를 적용해줘. 기존 문서와 에이전트 지침을 보존하고, 코드에서 확인한 내용으로 초기 문서를 작성해줘. 확인할 수 없는 내용은 미정으로 남겨줘.
이 저장소 자체를 템플릿으로 유지할 때는 예시와 빈칸을 그대로 둡니다. 특정 프로젝트의 정보를 자동으로 채우지 않습니다.
docs/design.md는 파일명 자체의 자동 로딩에 의존하지 않습니다. AGENTS.md의 공통 규칙으로 UI 작업 전에 필요한 부분을 읽도록 안내하며, UI와 무관한 작업에서 매번 읽거나 문서 전체를 항상 가져올 필요는 없습니다.
- 작업을 시작하면 docs/work/_template.md를 복사해
W-001-feature-login-session.md처럼 저장하고 문서 홈의 목록에 연결합니다. 파일명은W-번호-생성당시브랜치-주제.md형식이며, 브랜치명의/는-로 바꿉니다. - 같은 작업을 여러 세션이나 에이전트가 이어받아도 작업 문서 하나를 갱신합니다. 현재 상황은 최신 내용으로 정리하고, 중요한 시도와 판단은 날짜와 함께 남깁니다.
- ‘남은 일’은 체크리스트로 관리하고 완료 항목은
[x]로 남깁니다. ‘진행과 판단’에는 모든 완료 항목을 옮기지 않고, 중요한 변경·선택 이유·검증과 핵심 변경 파일 링크를 남깁니다. - 보류할 때는 작업 문서의 ‘현재 상황’에 보류 이유와 재개 조건을 적습니다. 재개할 때 조건 충족 여부를 확인합니다.
- 세션을 중단하거나 마치기 전에 결과, 검증 범위, 다음 행동을 적습니다. 종료 전에 기록하지 못할 경우를 대비해 중요한 변경 시점에도 갱신합니다.
- 긴 로그나 별도의 상세 설명이 필요할 때만 docs/sessions/_template.md를 사용합니다. 짧은 세션은 작업 문서의 세션 메모로 충분합니다.
- 작업 완료 후에도 파일과 링크를 유지합니다. 완료 조건을 확인한 뒤 상태를 바꾸고, 문서 홈에서는 최근 완료 목록으로 옮깁니다.
브랜치 변경·병합 후에도 작업 문서의 파일명은 유지하고, 실제 작업 브랜치는 문서 안의 코드 상태에 적습니다. 번호가 같아도 전체 경로가 다르면 다른 작업으로 구분합니다. 전체 파일명까지 겹치면 새로 추가하는 쪽에 짧은 구분자를 붙이고 링크를 맞춥니다. 공유 작업 목록은 다른 작업의 항목을 보존하며 합칩니다.
별도 TODO 파일은 만들지 않습니다. 해당 작업 문서의 ‘남은 일’에서 미완료 항목이 후속 작업 목록입니다. 독립적인 목표가 생기면 새로운 작업 문서를 만들고 서로 연결합니다.
첫 화면에서 현재 상황과 사람이 판단해야 할 사항을 알 수 있게 씁니다. 상태와 결론은 작업 문서에서 관리하고, 상세 세션 기록에는 당시의 근거를 둡니다.
예를 들어 로그인 오류 수정만 적기보다 다음처럼 기록합니다.
요청에 쿠키가 포함되지 않는 것을 확인해 전달 설정을 수정했다. 로컬 환경의 로그인과 새로고침 검증은 통과했다. 배포 환경 검증은 남아 있으며, 로그인 유지 기간은 제품 정책이 미정이다.
사실·추정·제안·확정된 결정을 구분하고, 테스트 결과나 관련 파일을 근거로 연결합니다. Markdown과 일반 상대경로 링크를 사용하므로 GitHub와 로컬 편집기에서 읽을 수 있습니다. 문서 도구에 연결할 때도 Git 저장소의 파일을 기준으로 관리합니다.
AGENTS.md를 지원하는 도구는 프로젝트 루트의 지침을 사용합니다. Claude Code는 CLAUDE.md의 @AGENTS.md를 통해 같은 지침을 읽습니다. 도구별 자동 인식 범위는 다르므로, 처음 적용한 뒤 에이전트에게 읽은 지침과 문서 경로를 확인합니다.
이 템플릿의 기록은 사람이나 에이전트가 작성합니다. 대화 전체를 자동 수집하거나 모델의 내부 세션 상태를 복원하는 기능은 포함하지 않습니다. 원문 보존이 필요하면 사용하는 도구에서 내보내고, 작업 문서에 필요한 근거를 연결합니다.
Git에는 공유할 문서와 검증 근거를 남깁니다. 공유하지 않을 원문·개인 메모는 기본적으로 무시되는 docs/.local/에 보관할 수 있습니다. 공유할 문서에 비밀값이나 불필요한 개인정보가 들어가지 않았는지 확인합니다. 문서를 커밋하고 공유하는 시점은 프로젝트의 Git 작업 규칙을 따릅니다.