developmentlisted

# 개발 규칙 (Development) > 코드를 작성·수정·검증할 때 따른다. IMPORTANT: 시스템/사용자 메시지가 이 스킬보다 우선한다. > 프로젝트 명령어는 `AGENT.md`의 표를, 절대 수정 금지 경로는 `.env, secrets/, .venv/, node_modules/`를 따른다. ## 0. 코드 짜기 전에 생각하기 (가장 싼 수정은 틀린 코드를 안 쓰는 것) - **가정을 말로 꺼낸다.** 사용자가 의도를 다 안 적었을 때, 무엇을 가정했는지 한 줄로 명시한다. - **모호하면 묵묵히 고르지 말고 드러낸다.** 두 해석이 다 맞는다면 둘 다 적고 묻는다. 잘못된 무언의 선택 한 번이 묻는 질문 한 번보다 비싸다. - **더 단순한 길이 있으면 push back 한다.** 시키는 대로만 하지 말고, 같은 문제를 더 작게 푸는 방법이 있으면 제안한다. - **막히면 멈춘다.** 무엇이 헷갈리는지 이름 붙여 묻는다. 혼란을 추측 코드로 덮지 않는다. ``` 나쁨: "유저 데이터 export 기능 추가해줘" → 곧장 csv/json/xml exporter 작성 좋음: "API 엔드포인트, 페이지네이션 JSON, PII 제외 필드만이라 가정. 맞나? 'export'는 다른 세 가지 의미도 가능 — 함께 보여드릴까요?" ``` ## 작업 흐름 (Read → Think → Plan → Edit → Verify) 1. **Read** — 고치기 전에 인접 코드·패턴을 읽고 이 레포의 관례를 파악한다. 라이브러리는 매니페스트(import/패키지 파일)로 존재를 확인한다. 2. **Think** — §0을 적용. 모호하면 *코드 짜기 전에* 먼저 묻는다. 3. **Plan** — 3단계 이상이거나 모호하면 `PLAN.md`에 단계를 적되 *단계마다 verify 줄을 함께* 적는다(§목표 주도 실행 참고). 4. **Edit** — 아래 규칙대로 최소 변경. 5. **Verify** — `.scripts/verify.sh`를 통과시킨다. 통과 전 "완료" 보고 금지. ## 브랜치 전략 (작업 공간) > 작업 공간 전략: **git worktree로 작업** - 작업마다 별도 워크트리를 만들어 메인 체크아웃을 건드리지 않는다: `git worktree add ../<프로젝트>-<작업명> -b <브랜치명>`. - 해당 워크트리 디렉터리에서 작업·커밋하고, 끝나면 PR로 병합한 뒤 `git worktree remove`로 정리한다. - `main` 체크아웃에서 직접 커밋하지 않는다. (여러 작업을 병렬로 격리할 때 유용하다.) ## 범위 규율 (가장 흔한 실패 모드) - **요청한 것만** 한다. 버그 수정에 주변 정리를 끼워넣지 않는다. - 비슷한 세 줄이 섣부른 추상화보다 낫다. 가상의 미래 요구를 위해 설계하지 않는다. - 기존 파일 수정 > 새 파일 생성. 반쪽 구현을 남기지 않는다. - 발견한 표류/죽은 코드는 고치지 말고 `.docs/plans/tech-debt.md`에 적고 넘어간다(범위 밖 청소는 별도 PR).