4team

Imported from ApptiveDev/4team (AGENTS.md). Install upstream with npx skills add ApptiveDev/4team. Copyright stays with the author.

AGENTS.md (루트) — 프로젝트 공통 규칙

사람과 AI 코딩 에이전트는 작업 전에 이 문서와 담당 영역 문서를 읽는다.

• API 계약의 단일 진실 공급원: docs/api-contract.md
• 프론트 전용 규칙: frontend/AGENTS.md
• 백엔드 전용 규칙: backend/AGENTS.md

API 요청·응답·enum·에러 형식은 이 파일에 중복 작성하지 않는다. 구현과 계약이 다르면 docs/api-contract.md가 기준이며, 계약 변경은 코드와 같은 PR에서 한다.

1. 제품 컨셉

• 부모와 자녀를 초대 코드로 1:1 연결한다.
• 매일 같은 질문 1개에 부모는 음성, 자녀는 텍스트로 답한다.
• 부모 원본 육성을 보존하고 STT·LLM 정리 텍스트를 보조로 제공한다.
• 자녀 답변은 부모에게 TTS로 들려준다.
• 질문 안내 음성은 질문 등록 시 사전 생성해 캐싱한다.
• 공개 정책의 세부 사항은 2026-09-25까지 회의로 결정한다. 프론트는 공개 조건을 계산하지 않고 API의 revealStatus, canViewPartnerAnswer만 사용한다.

2. 2026-10-02 MVP 범위

간편 가입 → 초대 코드 페어링 → 오늘 질문 → 부모 녹음/자녀 텍스트 답변
→ 원본 음성 저장 → STT/LLM 정리 → 서버가 판단한 공개 상태 → 지난 이야기

전화번호 인증, 가족 그룹, 소셜 피드, 푸시 완료 알림, 운영자 화면은 P1이다.

3. 저장소와 브랜치

main
└── dev (팀이 사용하기로 합의한 경우)
    ├── feature/<기능명>
    ├── fix/<기능명>
    ├── chore/<작업명>
    └── docs/<문서명>

• main에 직접 push하지 않는다.
• 한 기능은 한 브랜치와 한 PR로 작게 유지한다.
• 프론트 스캐폴드는 한 사람만 최신 main에서 생성한다.
• .env, API key, 실제 비밀번호, JWT secret을 커밋하지 않는다.
• .DS_Store, .idea, 빌드 결과물을 커밋하지 않는다.

4. API 계약 변경 절차

1. [API] 접두어로 GitHub Issue를 만든다.
2. 영향 받는 endpoint와 현재/제안 JSON을 적는다.
3. 프론트·백엔드 담당자가 확인한 뒤 docs/api-contract.md를 먼저 또는 코드와 함께 변경한다.
4. 계약, 백엔드 DTO/테스트, 프론트 Mock/모델을 같은 변경 단위로 맞춘다.
5. docs/api-contract.md 변경 이력에 한 줄을 추가한다.

5. 완료 기준

• 관련 테스트와 정적 분석을 통과한다.
• 로그에 토큰·음성 URL의 서명 query·개인정보를 남기지 않는다.
• API 변경이면 계약 문서와 Mock도 함께 갱신한다.
• 정상 화면뿐 아니라 loading, empty, retry, error 상태를 확인한다.