Imported from youngungyun/WhyUp (
AGENTS.md). Install upstream withnpx skills add youngungyun/WhyUp. Copyright stays with the author.
C203 프로젝트 작업 규칙
프로젝트 개요
- 서비스: AI Trading Hunter — 주간 수익률 기반 AI·사용자 모의투자 리그
- 구조: React 프런트엔드 + Spring Boot 백엔드 모노레포
- 기본 브랜치:
dev; 배포 기준 브랜치:main - 기획 근거: Notion C203의 PRD, 요구사항 명세서, 정책 정의서, API 명세서
작업 전 순서
.agent/workflow.md, 이 파일, 작업 대상 폴더의AGENTS.md를 읽는다.- 관련 Notion 원문과 API 계약을 읽고 Atlassian MCP로 Jira의 유사 Issue를 확인한다.
- 최신
dev에서<type>/<kebab-case>브랜치를 만들고 전체 Jira Key로 로컬 JSONL 로그를 시작한다. - 작업 유형에 맞는
.agents/skills/*/SKILL.md를 하나만 읽는다(backend-issue-workflow,db-migration등). 워크플로를 진행하는 Skill(start·impl·check·finish·review·handoff)은 그 하나에 포함되지 않는다.start를 쓰면 1~4가 자동으로 수행된다 — Codex는$start, Claude Code는/start. - 허용된 범위에서 최소 변경을 구현하고 의미 있는 문제·결정을 체크포인트로 기록한다.
- 로컬에서는 변경 대상 테스트와 필요한 lint·build, Secret 빠른 검사를 통과한다. 전체 테스트·커버리지 게이트는 MR CI에서 확인한다.
- Notion Work Log와 Jira를 갱신하고 MR에 변경, 검증, 위험과 미검증 항목을 기록한다.
브랜치·커밋
- 브랜치:
<type>/<kebab-case>(예:feat/login-api,fix/token-expire,chore/dependency-update) - 브랜치 이름에 Jira 번호를 넣지 않는다(
feat/63-login-api✗). Jira 연결은 MR 제목의 키가 한다. 첫 단어는 영문자로 시작한다. - 허용 type:
feat,fix,refactor,test,docs,infra,chore,perf,security - 커밋:
<type>: <명사형 요약>(깃모지 금지, 예:feat: 주문 생성 추가)- 요약은 명사형으로 끝낸다.
주문 생성 추가(O),주문 생성을 추가한다(X)
- 요약은 명사형으로 끝낸다.
- MR 제목:
<type>: <명사형 요약> (S15P21C102-XX)(고정, 예:feat: 주문 생성 추가 (S15P21C102-24)) main은 예외 없이 MR로만 병합한다(GitLab Protected Branch로 설정). force push는 모든 브랜치에서 금지한다.dev직접 push는 다음을 모두 만족하는 소규모 수정에만 허용한다(상세 절차:dev-hotfixSkill): ① 문서·주석·오타 수정 또는 dev 빌드/CI를 깨뜨린 원인의 즉시 수정 ② 변경 30줄 이하 1커밋 ③ API·DB·의존성 계약 변경 없음 ④ 커밋 컨벤션 준수 ⑤ push 후 dev Pipeline 녹색 확인(실패 시 즉시 revert). 조건을 벗어나면 MR 절차를 따른다.- MR 하나는 목적 하나, 300줄 이하를 권장한다. 병합은 Merge commit을 사용하고 source branch를 삭제한다.
수정 범위와 승인
- 일반 코드, 테스트, 개발 문서는 요청 범위에서 수정할 수 있다.
- 운영 설정, 배포 실행, DB migration 적용, CI credential, IAM/RBAC 변경은 사전 승인이 필요하다.
- 실제
.env, Secret, 토큰, 키, 인증서, 개인정보를 읽거나 출력하거나 커밋하지 않는다. git reset --hard, force push, 광범위 삭제, 운영 DB write/DDL을 실행하지 않는다.- 문서와 코드 계약이 다르면 임의로 선택하지 말고 불일치로 보고한다.
- 요청 범위 밖 개선(성능, 인덱스, 캐시, 리팩터링 등)은 즉시 구현하지 않고
improvement-backlogSkill로 기록한 뒤 원래 작업을 계속한다. - EC2 접속 정보와 SSH Key는 저장소에 넣지 않고 각 팀원의
~/.ssh또는 승인된 Secret 저장소에서 관리한다. - 배포 활성화는
S15P21C102-20의 공동 설계와 사용자 승인을 거쳐 별도 인프라 작업으로 진행한다.
공통 계약
- API prefix는
/api/v1을 사용한다. - API 경로는 복수 자원명과
kebab-case를 사용하고 행위는 HTTP Method로 표현한다. - 성공 응답은
{ "data": ..., "meta": null }, 실패 응답은{ "error": { "code", "message", "fieldErrors" }, "traceId": "..." }형태를 사용한다. - API 변경 시 OpenAPI와 계약 테스트를 같은 MR에서 수정한다.
- Entity·Schema 변경 시 Flyway migration과 호환성 계획을 포함한다.
.env.example에는 이름과 설명만 두고 실제 값은 넣지 않는다.- 로그에 비밀번호, 토큰, API Key, 개인정보를 남기지 않는다.
- 시세 등 외부 데이터는 계약된 API로만 가져온다. 웹 스크래핑을 기능 코드에 사용하지 않는다.
검증
npm run check # 로컬 Secret 빠른 검사 (자주)
npm run check:all # 전체 게이트가 별도로 필요할 때만 실행MR 전에는 변경 대상의 정상·실패·경계 테스트와 필요한 lint·build를 실행하고 실제 결과를 Work Log와 MR에 기록한다. MR CI가 전체 테스트·커버리지(LINE 80%·BRANCH 70%)와 계약·Secret 게이트를 강제한다. 머지 후 dev CI는 동일 tree 후보 또는 검증된 영역을 재사용하고, 재사용할 수 없을 때만 전체 검사한다. 로컬 npm run check:all은 명시적으로 전체 재현이 필요할 때만 실행하며 MR의 필수 조건이 아니다. 커버리지 미달 시 test-coverage Skill을 사용한다.
Hook이나 검증 스크립트가 차단하면 출력된 수정 명령을 그대로 따르고, 우회하지 않는다.
완료 보고에는 변경 파일과 이유, 실행한 검증과 결과, 남은 위험과 미검증 항목을 포함한다.
개선 효과를 확인할 수 있는 구현
- 모든 작업은 구현 전에 해결할 문제, 변경 전 상태, 개선 여부를 판단할 지표 또는 재현 시나리오를 정한다. 변경 코드와 함께 그 효과를 확인할 수 있는 테스트·계측·비교 실행 방법을 제공한다. 단순 문서·표기 수정은 해당 내용의 전후 확인으로 검증 범위를 맞춘다.
- 버그 수정은 실패하던 시나리오가 통과하는지, 기능 추가는 사용자 동작과 기대 결과가 성립하는지 확인한다. 성능 개선은 관련 시간·메모리·처리량·호출 횟수를 직접 측정하고 결과 정확성도 검증한다.
- 성능 비교는 같은 입력·설정·작업량과 명시된 측정 경계로 수행한다. 코드 버전, 입력 식별자/checksum, 실행 환경, 처리량, 성공/실패/중단 여부와 원시 결과를 기록한다. 시간 제한에 걸린 두 실행을 동일 작업량 완료로 취급하지 않는다.
- 전체 시간과 관련 단계별 시간을 함께 기록한다. 지연 평가 등으로 비용이 다른 단계로 이동한 것을 개선으로 보고하지 않는다. 중첩 시간·누적 시간·동시 실행의 대기를 중복 합산하지 않는다.
- 환경 변동이 있는 성능 비교는 반복 실행과 실행 순서, 개별 결과 및 대표값을 남긴다. 메모리 표본 최댓값과 실제 peak, 프로세스 RSS와 heap을 구분한다. 계측 오버헤드와 미측정 범위도 밝힌다.
- 완료 보고에는 변경 전 → 변경 후, 동일 결과/회귀 검증, 실행 명령과 결과 위치를 포함한다. 직접 측정, 추정, 미검증을 구분하며 합성 실험의 절감량을 서버 호출 수에 곱해 서버 실측처럼 보고하지 않는다.
- 실측 자료나 실행 환경이 없으면 검증 도구와 누락 조건을 구체적으로 남기고 효과 검증은 미완료로 표시한다. 검증을 위해 운영 승인·Secret·배포 규칙을 우회하지 않는다.
