tasteby/CLAUDE.md

tasteby — Engineering Standards & AI Persona Pipeline

이 파일은 모든 AI 페르소나가 따르는 단일 진실 기준(SoT) 이다.

0. 필수 참조 (Tasteby 고유)

• 모든 작업 시작 전에 /skills 슬래시 커맨드를 실행하거나, mcp__oracle-26ai-vector__search_similar로 관련 스킬을 검색하여 적용할 규칙을 확인할 것
• 작업 완료 후 새로운 스킬/지식이 생기면 벡터 스토어에 기록할 것
• 코드 변경 시 CHANGELOG.md 업데이트 필수

1. 잘 설계된 코드 원칙

• 작게·단일 책임(함수 ≤ ~40줄), I/O 와 순수 로직 분리(테스트 가능성).
• 설정·비밀은 .env 에서 주입(하드코딩 금지). 명시적 에러 처리(삼키지 말 것).
• 외부 입력은 경계에서 검증. 의도를 드러내는 네이밍. 주석은 '왜'만.
• 핵심 로직은 테스트 없이 머지 금지. 모든 변경은 Redmine 이슈 ↔ 설계서 ↔ git 커밋으로 연결.
• 디자인 패턴 적용 (메모리의 feedback_design_patterns.md 참조).

2. 설계서 우선 (Design-First — 하드 게이트) ⛔

설계서 없이는 코드 없음. 함수가 설계서로 덮이기 전엔 구현하지 않는다.

• Architect 가 구현 전 docs/design/<issue-id>-<slug>/README.md(_TEMPLATE.md)에 모든 함수를 등재.
• 복잡 함수(분기/상태·외부 I/O·리스크 경로·비자명 알고리즘)는 fn-<name>.md(_FN_TEMPLATE.md).
• Developer 는 설계서 없으면 구현 거부 → 02-Architect 로 반려.
• 코드가 설계와 달라지면 설계서를 먼저 고친다. 되돌리기 어려운 결정은 ADR(docs/adr/).

3. 문서 아키텍처

Diátaxis + ADR + 설계서. 지도: docs/README.md.

종류	위치	시점
설계서	docs/design/	구현 전
ADR	docs/adr/	결정 시
레퍼런스	docs/reference/	구현 후
가이드	docs/guides/	릴리스 시

4. Git 규율

• 모든 산출물 = git 커밋 + Gitea push("추적 안 된 변경" 금지).
• 커밋: [<Persona>] #<issue-id> <요약> ... Refs #<issue-id>.
• .env 등 비밀 커밋 금지(.gitignore 차단).

5. AI 페르소나 파이프라인 (완전 자동)

[01 Planner]→[02 Architect]→[03 Developer]→[04 QA]→[05 Designer]→[06 Reviewer]→[07 Release]→[08 Documenter]→[09 Done]
        (설계서)        (설계서 게이트)              └──── 반려 ────┘ (QA/Reviewer/설계서누락 시)

• 작업 큐 = Redmine 이슈(project tasteby). 프로토콜: docs/pipeline/QUEUE-PROTOCOL.md.
• 현재 단계 = 이슈 카테고리(01-Planner…09-Done). 수명주기 = 이슈 상태.
• 페르소나: .claude/agents/. 오케스트레이터: .claude/workflows/persona-pipeline.js.

6. 게이트

• 설계서 게이트(02→03), QA 게이트(04), Reviewer 게이트(06). 우회 금지, 반려 사유는 저널 노트.

7. 응대 규칙

• 존댓말 사용 (반말 금지).

8. 개발 환경 (Tasteby 고유)

• 새 HTTP 메서드 추가 시 WebConfig.java CORS allowedMethods 확인.
• 백엔드 코드 수정 후 빌드 성공 확인 → PM2 재시작.
• dev 환경 PM2 설정 변경 금지 (tasteby-web: PORT=3001, tasteby-api: 8000).

9. 작업 환경

• Gitea: https://gittea.cloud-handson.com/joungmin/tasteby (branch main)
• Redmine: https://redmine.cloud-handson.com/projects/tasteby
• 자격증명은 .env 에서 로드.