Gnuboard5/AGENTS.md

저장소 작업 지침

적용 범위

이 문서는 저장소 루트와 모든 하위 디렉터리에 적용한다.

문서 작성 언어

• README, 보안 정책, 설치 안내, 개발 가이드 등 저장소 문서는 원칙적으로 한국어로 작성한다.
• 파일명, 코드 식별자, 명령어, API 명칭, 설정값과 외부 서비스의 고유 명칭은 원문을 유지한다.
• 영문 문서나 번역본이 별도로 필요한 경우에는 해당 작업에서 명시적으로 요청된 범위에 한해 추가한다.

커밋 메시지

• 커밋 메시지는 한국어로 작성한다.
• 제목은 <접두어>: <변경 내용> 형식을 사용한다.
• 접두어는 아래 권장 목록에서 변경 목적에 가장 가까운 항목을 선택한다.
• 변경 대상을 포함해 무엇을 왜 변경했는지 알 수 있도록 구체적으로 작성한다.
• 수정, 업데이트, 작업처럼 변경 내용을 식별하기 어려운 표현만 사용하지 않는다.
• 하나의 커밋에는 가능한 한 하나의 목적에 해당하는 변경만 포함한다.
• 제목만으로 설명이 부족하면 본문에 변경 이유, 영향 범위와 검증 방법을 추가한다.
• 관련 이슈가 있으면 커밋 본문이나 꼬리말에 이슈 번호를 기록한다.

권장 접두어

• feat: 새로운 기능 추가
• fix: 버그 또는 잘못된 동작 수정
• security: 보안 취약점 수정이나 보안 강화
• docs: 문서 추가 또는 변경
• refactor: 동작 변경 없는 코드 구조 개선
• perf: 성능 개선
• test: 테스트 추가 또는 변경
• build: 빌드 시스템이나 의존성 변경
• ci: CI/CD 설정이나 자동화 변경
• chore: 기능과 직접 관련 없는 유지보수 작업
• revert: 이전 변경 되돌리기

보안 이슈 식별자

• KVE, CVE 등 식별자가 부여된 보안 이슈를 조치하는 커밋은 제목에 관련 식별자를 반드시 병기한다.
• 식별자는 security: 접두어 바로 뒤에 원문 그대로 작성한다.
• 하나의 커밋이 여러 보안 이슈를 함께 조치하면 관련 식별자를 모두 병기한다.
• 예: security: KVE-2026-1909 모바일 KCP Windows 명령 인자 주입 차단

작성 예시

• docs: Git과 압축파일 설치 절차를 구분해 README에 안내
• fix: 품목 일부 취소 시 PG 취소금액 불일치 수정
• security: KVE-2026-1899 상품 정렬값 화이트리스트 검증으로 SQL 삽입 차단
• refactor: 객체 캐시의 유형별 저장 키 생성 로직 분리