sodalive-android/docs/agent-guides/workflow-docs-commits.md

workflow-docs-commits

SodaLive 저장소에서 작업 절차, docs 계획 문서 규칙, 커밋 규칙을 정리한 문서다.

커밋 메시지 규칙 (표준 Conventional Commits)

• 커밋 상세 가이드/절차는 .opencode/skills/commit-policy/SKILL.md를 단일 기준으로 사용한다.
• 커밋 작업 시작 시 skill 도구로 commit-policy를 먼저 로드한다.
• 기본 형식은 <type>(scope): <description>를 사용한다.
• type은 소문자(feat, fix, chore, docs, refactor, test 등)를 사용한다.
• 제목(description)은 한글로 작성하고, 명령형/간결한 현재형으로 작성한다.
• 이슈 참조 footer는 Refs: #123 또는 Refs: #123, #456 형식을 사용한다.

커밋 메시지 검증 절차

• git commit 직전/직후 work/scripts/check-commit-message-rules.sh를 실행해 규칙 준수 여부를 확인한다.
• 스크립트 결과가 [FAIL]이면 메시지를 수정한 뒤 다시 검증한다.

작업 절차 체크리스트

• 변경 전: 유사 기능 코드를 먼저 찾아 네이밍/예외/응답 패턴을 맞춘다.
• 변경 중: 공개 API 스키마를 임의 변경하지 말고 작은 단위로 안전하게 수정한다.
• 변경 후: 최소 단일 테스트(--tests) 또는 ./gradlew :app:test를 실행하고 필요 시 ./gradlew :app:ktlintCheck를 수행한다.

작업 계획 문서 규칙 (docs)

• 모든 구현 작업은 PRD 문서와 구현 계획/TASK 문서가 모두 준비된 뒤에 시작한다.
• 사용자가 프롬프트를 입력하면 먼저 PRD 문서를 작성한다.
• PRD 작성 중 애매하거나 더 필요한 내용, 결정해야 하는 사항이 있으면 애매한 사항이 없어질 때까지 사용자와 인터뷰한다.
• 인터뷰로 확정한 내용을 PRD 문서에 보강한 뒤, 해당 PRD를 기준으로 구현 계획/TASK 문서를 작성한다.
• 구현은 계획/TASK 문서를 기준으로 필요한 내용만 최소 범위로 진행한다.
• PRD 문서는 docs/prd/ 아래에 작성한다.
• 구현 계획/TASK 문서는 docs/plan-task/ 아래에 작성한다.
• PRD 문서는 sample-prd.md 파일에서 작업에 필요한 부분만 발췌해 작성한다. sample-prd.md가 없거나 위치가 불명확하면 추측하지 말고 사용자에게 확인한다.
• PRD 문서 파일명은 기존 계획 문서 파일명 규칙을 따르되, 계획 문서와 구분되도록 prd 표기를 포함한다.
• 계획/TASK 문서 파일명은 [날짜]_구현할내용한글.md 형식을 사용한다.
• 날짜는 YYYYMMDD 8자리 숫자를 사용한다.
• 연속된 하나의 작업이라면 별도 새 문서를 만들지 말고 기존 PRD와 계획/TASK 문서에 추가 작업으로 이어서 기록한다.
• 구현 항목은 기능/작업 단위 체크박스(- [ ])로 작성하고 완료 즉시 - [x]로 갱신한다.
• 작업 도중 범위가 변경되면 계획 문서 체크리스트를 먼저 업데이트한 뒤 구현한다.
• 결과 보고 시 문서 하단에 검증 기록(무엇/왜/어떻게, 실행 명령, 결과)을 한국어로 남긴다.
• 후속 수정이 발생해도 기존 검증 기록은 삭제/덮어쓰기 없이 누적한다.

문서 유지보수 규칙

• build.gradle/app/build.gradle/settings.gradle 변경 시 실행 명령 섹션을 함께 갱신한다.
• 테스트 클래스 추가/이동 시 단일 테스트 실행 예시를 최신 상태로 유지한다.
• .editorconfig 변경 시 포맷 규칙 섹션을 동기화한다.
• 문서 변경 후 최소 한 번 ./gradlew tasks --all로 명령 유효성을 확인한다.
• 불확실한 규칙은 추측으로 채우지 말고 근거 파일 경로를 먼저 확인한다.
• 에이전트 안내 문구는 한국어 중심으로 유지한다.