코드 작성 가이드라인

승인된 계획에 따라 코드를 작성할 때 준수해야 할 규칙. 각 항목에 이유를 붙여 두었다 — 이유가 성립하지 않는 상황인지가 예외 판단의 기준이다.

코드 작성 시 준수 사항

• 레이어 구조 준수: 01-architecture-check의 레이어 순서를 지키고, 각 레이어의 역할을 넘지 않는다.
• 기존 패턴 따르기: 새 파일은 같은 레이어의 기존 파일 패턴을 참고한다 — 패턴이 갈리면 리뷰(영향 범위 탐색)와 유지보수가 파일마다 달라진다.
• 쿼리 파라미터 바인딩: raw 쿼리를 쓸 때는 반드시 placeholder를 쓴다 (인젝션 방지). 문자열 연결로 쿼리를 만들지 않는다.
• 에러 처리: 프로젝트에 정의된 에러 클래스를 쓴다 — 응답 규약이 표준과 다른 프로젝트에서는 생 에러를 던지면 클라이언트가 원인을 식별할 수 없다.
• 캐시 무효화: 데이터 변경 시 관련 캐시 삭제 로직을 포함한다 — TTL이 없는 캐시는 무효화를 빠뜨리면 낡은 데이터가 무기한 서빙된다.
• 트랜잭션: 여러 테이블을 함께 바꿀 때는 원자성을 보장한다 — 중간 실패로 부분 커밋이 남으면 연관 엔티티 간 정합성이 깨진다.

보안 체크리스트

• 출력 이스케이프 (HTML·로그·외부 전달 포맷 각각)
• 사용자 입력 검증 (스키마 검증 또는 명시적 수동 검증)
• credential은 설정·환경 변수로만 관리. 코드·커밋에 남기지 않는다
• 새 엔드포인트에 적절한 인증 방식 적용

테스트 작성 필수 케이스

• 새로운 엔드포인트
• 비즈니스 로직 변경
• 보안 관련 로직
• 복잡한 계산 로직 (날짜·시간·금액·반복 규칙 등 경계가 많은 것)

테스트 작성 규칙

구체적인 파일명·디렉터리·모킹 방식은 test-writer 스킬을 따른다 (test-skill-installer로 프로젝트에 맞게 생성된다). 공통 원칙만 여기 둔다.

• 기존 테스트 컨벤션을 따르고, 없는 부분만 채운다
• 외부 의존성은 모킹하고, 테스트가 서로의 상태에 의존하지 않게 한다
• 데이터 저장소를 쓰는 테스트는 정리(롤백·초기화) 경로를 반드시 둔다

코딩 후 검증

1. 테스트 러너를 실행해 기존 + 신규 테스트 통과를 확인한다
2. 프로젝트에 정적 검사(린트, 순환 의존성 검사, 타입 체크)가 있으면 함께 돌린다
3. 7단계(pre-commit-review)로 진행해 커밋 전 최종 검증을 받는다

구체적인 명령은 02-guidelines 또는 프로젝트 CLAUDE.md에 적힌 것을 쓴다.