agent-guide.md

AI 에이전트 작업·문서화 가이드

이 문서는 LLM 기반 에이전트들이 컨텍스트 손실에도 불구하고 일관되게 협력하기 위한 표준을 제시한다.

핵심 원칙

문서는 미래의 에이전트를 위한 것이다. 매 대화가 끝나면 기억을 잃는 LLM의 특성상, "다음 에이전트가 30분 안에 같은 상태로 복귀"할 수 있도록 저장소 내 파일에 모든 결정과 진행상황을 기록해야 한다.

핵심 문서 5개

1. README.md — 5분 안에 프로젝트를 파악할 수 있는 신규 합류자용 안내
2. SKILL.md — 에이전트가 작업 전 반드시 읽어야 할 불변조건과 "하지 말 것" 규칙
3. docs/resume.md — 현재 진척도와 다음 작업(1시간 분량)을 명시
4. docs/journal.md — append-only 작업 일지(수정 불가, 역시간순 추가)
5. docs/decisions.md — 아키텍처 결정 기록(ADR 형식)

새 세션의 재개 프로토콜

신입 에이전트는 다음 순서대로 10분 안에 컨텍스트를 확보한다:

1. README.md 전체 (2분)
2. SKILL.md의 "프로젝트 불변조건" (3분)
3. 최근 docs/journal.md 엔트리 3개 (2분)
4. docs/resume.md의 진척도와 다음 작업 (1분)
5. 관련 docs/decisions.md ADR 검토 (2분)

작업 체크리스트

각 작업 완료 후:

• docs/journal.md에 새 엔트리 추가 (절대 기존 항목 수정 금지)
• docs/resume.md의 진척도 갱신 및 다음 작업 명시
• 의사결정이 있으면 docs/decisions.md에 ADR 추가
• 코드 변경 시 필수 검증(pytest, ruff check ., mypy src/kma) 통과 확인
• 사용자 가시 변경이면 CHANGELOG.md 갱신

핵심 규칙

문서를 갱신하지 않은 작업은 절반만 끝난 것이다. 코드만 바뀌고 journal과 resume이 최신이 아니면 다음 에이전트가 컨텍스트를 복구할 수 없다.