AGENTS.md

작업 시작 전 반드시 git pull을 실행합니다.

WhyLog 개발 가이드

WhyLog 모노레포에서 개발자와 AI 에이전트가 따라야 하는 공통 규칙과 문서 위치를 안내합니다.

파트별 문서 인덱스

• AI: AI 기술 스택, 폴더 구조, LLM 호출 규약, 프롬프트 관리, 참조 구현
• Server: 서버 계층 구조, 트랜잭션·쿼리 규칙, 응답 형식, 경계, 참조 구현, 리뷰 체크리스트
• Web: 프론트엔드 구조, 컴포넌트·상태 관리·스타일 규칙, 참조 구현

공통 문서

• Architecture: AI·Server·Web 연결 구조와 서비스 흐름
• Domain: 공통 용어와 비즈니스 규칙
• Decisions: 회의에서 확정된 결정 사항, YYYY-MM.md로 월별 관리
• PR Reviews: PR별 CI 리뷰 기록 형식과 조회 규칙

저장소 구조

• ai/: AI 서비스
• server/: Spring Boot 백엔드
• web/: 프론트엔드
• docs/: 공통 설계 및 결정 기록

문서 관리 원칙

• 문서의 정본은 저장소 내부의 AGENTS.md와 docs/입니다.
• 실제 규칙은 AGENTS.md에만 작성합니다.
• CLAUDE.md는 같은 폴더의 AGENTS.md를 가리키는 심볼릭 링크로 관리합니다.
• 각 파트에 문서를 추가하거나 경로를 변경하면 해당 파트의 문서 목차도 함께 갱신합니다.
• 파트 문서 구성이 변경되면 루트의 파트별 문서 인덱스도 함께 갱신합니다.
• 파트 목차와 루트 인덱스 중 하나만 누락된 경우 기록성 수정으로 보고 바로 PR로 반영합니다.
• 회의에서 확정된 결정은 docs/decisions/YYYY-MM.md에 월 단위로 기록합니다. 해당 월 파일이 없을 때만 새로 만들고 docs/decisions/README.md 인덱스를 갱신합니다.
• docs/pr-reviews/는 규칙이 아닌 실행 기록입니다. 에이전트는 현재 작업과 관련된 PR 문서만 선택해서 읽습니다.
• AI가 회의 녹음에서 뽑은 초안은 그대로 머지하지 않습니다. 기록 담당이 결정만 남기고 서술·요약·배경 설명을 걷어낸 뒤 PR을 올립니다. 월별 decisions.md에는 결정 한 줄과 날짜만 들어갑니다.

문서 분량

• 각 AGENTS.md는 150줄을 넘지 않습니다. 넘으면 해당 파트 폴더 아래로 분리하고 AGENTS.md에는 목차만 남깁니다.
• 줄을 추가할 때 "이 줄을 지우면 AI가 실수하게 되나?" 를 묻습니다. 아니면 쓰지 않습니다.
• 코드를 읽어서 알 수 있는 것(기술 스택, 폴더 트리, 파일별 설명)은 쓰지 않습니다.
• 규칙을 반복해서 어긴다면 문서가 길어서 규칙이 묻힌 것으로 보고, 규칙을 강조하기 전에 분량부터 줄입니다.

기본 작업 절차

1. 작업 시작 전 git pull을 실행합니다.
2. 기능 요구사항에서 모호한 부분을 먼저 질문하고 완료 조건을 확정합니다.
3. 작업을 작은 단위로 나눕니다.
4. 예상 소요 시간, 막힐 가능성이 있는 부분, 전문 밖 영역에 대한 걱정을 기록합니다.
5. 구현 시작 시 작업 중 PR을 생성합니다.
6. 다른 파트의 영역을 수정할 때는 해당 가디언에게 PR 코멘트로 설계를 확인합니다.
7. 설계 확인 요청에 24시간 동안 응답이 없으면 판단한 내용을 기록하고 진행합니다.
8. 기계 검사와 AI 리뷰의 차단 항목이 없으면 머지합니다.
9. 실제 소요 시간, 실제로 막힌 부분, 배운 점을 기록합니다.

커밋 메시지

• 형식은 <type>(<scope>): <설명>입니다.
• type은 feat, fix, refactor, docs, chore, ci, style, test 중 하나만 사용합니다.
• scope는 ai, server, web, docs, root 중 하나만 사용합니다.
• 여러 파트를 동시에 변경하면 scope를 생략해 <type>: <설명>으로 작성합니다.

브랜치 이름

• 형식은 <type>/<short-description>입니다.
• type은 커밋 메시지와 같은 목록을 사용하고, short-description은 영문 소문자 kebab-case로 작성합니다.
• Issue·PR 번호와 # 문자는 넣지 않습니다. 예: feat/meeting-summary, ci/ai-review.

검사 및 리뷰 원칙

• 기계 검사는 포매터, 린터, 타입 검사, 테스트를 포함합니다.
• 기계 검사 실패 시 AI 리뷰를 실행하지 않습니다.
• AI 리뷰는 루트 문서, 변경된 파트의 AGENTS.md, 공통 문서와 기능 완료 조건을 기준으로 수행합니다.
• AI 리뷰 결과는 반드시 차단과 제안으로 구분합니다.
• 차단 항목은 타당성을 사람이 먼저 판단한 뒤 필요한 항목만 수정합니다.
• 제안 항목은 머지를 차단하지 않습니다.
• 공용 모듈이나 데이터 구조 변경은 관련 가디언의 확인이 필요합니다.
• 로컬 AI는 구현에 사용하고, 공식 리뷰 기록은 CI의 AI 리뷰를 사용합니다.

AI 사용 원칙

작업 방식

• 가정을 먼저 말합니다. 모호하면 추측하지 말고 질문하고, 트레이드오프가 있으면 드러냅니다.
• 최소 코드로 해결합니다. 요청하지 않은 추상화와 예비 기능을 만들지 않습니다.
• 요청한 것만 건드립니다. 변경된 모든 줄이 요청과 직접 연결되어야 합니다. 무관한 포매팅·주석·리팩터링을 함께 하지 않습니다.
• 완료 조건을 먼저 정의하고 검증될 때까지 반복합니다.
• 단, diff를 한 문장으로 설명할 수 있으면 위 절차를 건너뜁니다.

팀 규칙

• AI가 생성한 코드를 이해하지 못한 상태로 머지하지 않습니다.

• 참조 구현이 있는 경우 해당 경로를 AI에게 함께 제공합니다.

• 스키마나 공용 인터페이스 변경은 AI가 바로 적용하지 않고 먼저 제안하도록 합니다.

• 동시에 여러 AI 작업을 병렬로 진행하지 않습니다.

• 출력 길이를 예측할 수 없는 명령은 바이트로 자릅니다. head -n은 한 줄이 거대하면 무력합니다.

  ./gradlew build 2>&1 | tail -c 4000