Imported from jangjisu/rest-route (AGENTS.md). Install upstream with npx skills add jangjisu/rest-route. Copyright stays with the author.

rest-route 작업 규칙

이 파일은 Codex/agent가 rest-route에서 작업할 때 먼저 읽는 진입점이다.

기본 원칙

• 작업:으로 시작하는 요청만 하네스 실행 모드로 처리하고, 브랜치/파일 수정/검증/커밋을 수행한다. 원격 브랜치 push는 자동으로 수행하지 않고, 사용자가 직접 검증한 뒤 명시적으로 요청할 때만 수행한다.
• 그 외 요청은 상담 모드로 처리하며, trade-off 설명, 계획 제안, 질문 답변만 수행하고 파일은 수정하지 않는다.

작업 항목 분리 원칙

• 작업: 요청 안에 독립적인 변경 항목이 2개 이상 있으면, 먼저 항목을 나눠 제시하고 하나씩 순서대로 진행한다.
• 한 항목이 끝나면 다음 항목을 이어서 진행할지 사용자에게 확인한다.

작업 카테고리 분리 원칙

작업 항목이 하나로 확정되면, 계획과 구현은 백엔드/프론트엔드 구분 없이 하나의 작업 단위로 진행한다. 카테고리(Java/backend, Frontend 등)는 이후 커밋을 나눌 때만 사용하고, 카테고리별로 진행 순서를 확인하거나 카테고리마다 별도로 계획·리뷰를 반복하지 않는다.

작업 범위 원칙

• 요청을 해결하는 데 필요한 최소한의 코드 변경/추가를 우선한다.
• 기존 구조와 패턴을 먼저 따르고, 새 추상화나 새 계층은 꼭 필요할 때만 추가한다.
• 사용자가 요청하지 않은 리팩토링, 구조 변경, 파일 이동은 하지 않는다.
• 버그 수정 요청에서 주변 변수명, 메서드명, 줄바꿈, 포맷팅을 임의로 바꾸지 않는다.
• 수정 대상 파일의 전체 포맷팅이나 import 정리는 요청 해결에 필요한 경우에만 수행한다.
• 중복 제거보다 변경 범위 축소를 우선한다. 단, 중복이 실제 버그나 유지보수 문제를 만들 때만 정리한다.
• 기능 구현 중 발견한 별도 개선점은 바로 처리하지 말고 사용자에게 후속 작업으로 제안한다.
• 반복 가능한 패턴 위반(코딩 스타일, 명명, 구조 등)을 발견하면, 고칠지와는 별개로 rules/ 문서에 규칙으로 남길지 먼저 제안한다. 이미 같은 규칙이 문서에 있는지 먼저 확인하고, 없을 때만 제안한다.

Git 작업 원칙

• 기능 작업을 시작하기 전에 현재 브랜치를 확인하고, 다음 기준으로 새 브랜치를 만들지 현재 브랜치에서 이어갈지 정한다. 판단이 모호하면 사용자에게 먼저 확인한다.
  • 현재 브랜치 유지: 지금 열려있는(머지 안 된) PR의 범위 안에서 나온 후속 수정이나 버그
  • 새 브랜치: PR 목적과 무관한 새 요청, 또는 이미 머지된 코드에 대한 별개 이슈
• 기본 브랜치(main, master)에는 직접 커밋하지 않는다.
• agent의 기본 역할은 작업 브랜치에 변경을 커밋하는 것까지이다. 원격 브랜치 push는 자동으로 수행하지 않고, 사용자가 직접 검증한 뒤 명시적으로 요청할 때만 수행한다.
• PR 생성, PR 검토, 기본 브랜치 병합은 사용자가 직접 수행한다.
• 브랜치명을 새로 만들 때는 기본적으로 codex/ prefix를 사용한다.

UI 변경 원칙

• 화면(UI) 변경이 있는 작업은 계획 단계에서 화면 전체가 바뀌는지 일부만 바뀌는지 정한다.
  • 화면 전체가 바뀌면 모바일/데스크톱 예상 화면을 보여주는 HTML 목업을 만든다.
  • 화면 일부만 바뀌면 계획 문서에 무엇이 어떻게 바뀌는지 스펙으로 기록한다.
• 구현이 아직 필요하지 않다면 계획(및 목업)만 전달하는 것으로 충분하다.

작업 카테고리

문서/하네스 작업은 코드/API/프론트/Git 작업과 직접 섞이지 않으면 단일 카테고리로 처리한다.

작업 전 참고 문서

항상 모든 문서를 읽지 않는다. 요청 카테고리를 먼저 판단한 뒤, 작업 판단에 필요한 문서만 추가로 읽는다.

구현 작업의 방향을 정할 때는 다음 기준 문서 중 영향이 있는 문서만 읽는다.

PRODUCT.md       제품 범위와 사용자 가치
USER_INSIGHTS.md 사용자 유형, 행동 가설과 다음 브레인스토밍 질문
DATA.md          데이터 저장, 관계와 연결 키
ARCHITECTURE.md  레이어 책임과 코드 구조
QUALITY.md       테스트와 품질 기준

규칙 문서는 하네스 검사를 대체하지 않는다. 기계적으로 검증 가능한 항목은 harness/hooks가 판단하고, 규칙 문서는 설계 방향과 예외 판단에만 사용한다.

Git 커밋 관련 요청이면 harness/steps/06-commit.md 를 기준으로 한다.

새 API 연동 관련 요청이면:

rules/api-integration.md

Java/backend 파일 수정이면:

rules/backend/index.md

JS, HTML, CSS 파일 수정이면:

rules/frontend.md

하네스 작업 흐름

백엔드/API/프론트처럼 구현이 필요한 작업은 다음 6단계를 기준으로 진행한다. 구현 작업에서는 프로젝트 Skill인 vroom-workflow를 사용하며, 상세 역할과 실행 순서는 harness/WORKFLOW.md에서 확인한다.

1. 계획 생성
2. 스펙 영향도 확인
3. 계획 확정 및 사용자 승인
4. 코드 작성
5. 검증
6. Commit (push는 사용자 요청 시 별도 수행)

각 단계의 목적은 harness/steps 문서를 기준으로 확인하고, 검증은 harness/harness.sh verify <step>으로 수행한다.

스펙 영향도 확인은 백엔드 작업에서 항상 수행한다. 스펙이 바뀌지 않는 작업이라도 "변경 없음"과 그 이유를 확인한다.

스펙 확인 결과와 trade-off를 계획에 반영하고 사용자 승인을 받아야 코드 작성을 시작할 수 있다.

코드 작성 뒤에는 코드, 테스트와 관련 Markdown 기준 문서의 정합성을 작업 전체에서 한 번만 리뷰한다. 리뷰 지적을 반영한 뒤 재리뷰나 Compound Engineering 리뷰를 실행하지 않고 자동 검증으로 종료한다.

Agent skills

Issue tracker

GitHub Issues를 gh CLI로 사용한다. 자세한 내용은 docs/agents/issue-tracker.md 참고.

Triage labels

기본 5개 라벨(needs-triage/needs-info/ready-for-agent/ready-for-human/wontfix)을 그대로 쓴다. docs/agents/triage-labels.md 참고.

Domain docs

Single-context 구조. 루트 CONTEXT.md(프로젝트 전용 용어집)와 docs/domain/*.md(실제 도메인 위키 — 흐름·정책·API 계약, jisu-dev:domain-wiki 스킬이 갱신)를 함께 쓴다. docs/agents/domain.md 참고.