From 19894a40022550760af315dd4b5db2bf5bd93234 Mon Sep 17 00:00:00 2001 From: juhyuni Date: Sun, 11 Oct 2026 07:11:07 +0000 Subject: [PATCH 1/4] =?UTF-8?q?[DOCS]:=2007-workflow=20=EB=A5=BC=20?= =?UTF-8?q?=EA=B3=B5=ED=86=B5=20=ED=95=98=EB=84=A4=EC=8A=A4=20=EC=B0=B8?= =?UTF-8?q?=EC=A1=B0=20+=20=ED=94=84=EB=A1=9C=EC=A0=9D=ED=8A=B8=20?= =?UTF-8?q?=EC=A0=84=EC=9A=A9=20=EC=82=AC=ED=95=AD=EC=9C=BC=EB=A1=9C=20?= =?UTF-8?q?=EC=9E=AC=EA=B5=AC=EC=84=B1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 규약 1~6 본문을 ~/.claude/rules/ 로 이관하고 구 규약 번호 대응표 추가 - PR 직후 loop.md cron 자동 등록 폐지, loop.md 는 수동 /loop 보조 수단으로 - gh-meta.sh · pr-resolve-comments.sh · nb-clean · Python 의존성 규칙 유지 Co-Authored-By: Claude Fable 5.1 --- .claude/rules/07-workflow.md | 328 +++++++---------------------------- 1 file changed, 61 insertions(+), 267 deletions(-) diff --git a/.claude/rules/07-workflow.md b/.claude/rules/07-workflow.md index 5ee938f..1ddc20e 100644 --- a/.claude/rules/07-workflow.md +++ b/.claude/rules/07-workflow.md @@ -1,304 +1,98 @@ -# AI 작업 진행 규약 +# AI 작업 진행 규약 — 본 프로젝트 전용 사항 -이 문서는 Claude / Copilot 등 AI 협업 도구가 본 프로젝트에서 작업을 진행할 때 따라야 하는 -**workflow 규약** 입니다. 작업 도중 사용자 승인을 빈번히 요청하여 흐름이 끊기는 문제를 -해소하고, AI 의 자율성과 안전성의 균형을 명문화합니다. +공통 규약은 사용자 레벨 하네스 **`~/.claude/rules/`** 에 있다 (2026-10-11 이관, 이슈 #84). +이 문서는 **공통 규약이 프로젝트에 위임한 값** 과 **본 저장소만의 추가 규칙** 만 적는다. +공통 규약과 충돌하면 이 문서가 우선한다. 코드 자체의 규약은 [01-architecture.md](01-architecture.md) ~ +[06-code-style.md](06-code-style.md). -본 규약은 코드 스타일 / 아키텍처 / 테스트 등 **무엇을 만드느냐** 가 아니라, **어떻게 -진행하느냐** 를 다룹니다. 코드 자체의 규약은 [01-architecture.md](01-architecture.md) ~ -[06-code-style.md](06-code-style.md) 참조. +> `~/.claude/rules/` 가 없는 환경 (CI 등) 에서는 [CLAUDE.md](../../CLAUDE.md) 의 "반드시 지킬 규칙" 과 +> "AI 작업 진행 규약" 요약, 그리고 이 문서만 적용된다.
-## 핵심 6 규약 +## 구 규약 번호 → 공통 하네스 대응표 -### 1. 이슈 먼저 (issue-first) 생성 정책 +기존 이슈 · PR · 문서 · 스크립트 주석 (`scripts/gh-meta.sh` 등) 이 "규약 N" 으로 참조한다. 번호는 그대로 쓴다. -사용자 작업 지시가 도착하면 **코드 수정 시작 전에 GitHub 이슈를 먼저 생성** 한다. - -#### 원칙 - -- 모든 작업은 GitHub 이슈로 추적 — branch / commit / PR 모두 그 이슈를 참조 -- **이슈 생성 시 Label · Issue Type 부여 필수** (규약 6 매핑 표 참조) -- **규모가 PR 1개로 reviewable diff 안 되면 메인 이슈 + sub-issue N개로 분할** 하여 모두 사전에 생성 - - 메인 이슈 본문에 전체 그림 + sub-issue 목록 + 완료 조건 명시 - - **GitHub 의 Sub-issue 기능 + Relation 적극 활용** — `gh api graphql` 의 `addSubIssue` mutation 으로 메인 ↔ sub 관계 활성화하여 GitHub UI 에서 계층 명시 - - 본문 link (`Parent: #<메인>`) 만으로 표기하던 기존 방식은 보조용. native sub-issue 가 우선 -- 각 sub-issue 단위로 `branch → 작업 → commit → PR` 사이클 반복 -- PR closing reference 는 그 sub-issue (`Closes #`). 메인 이슈는 모든 sub-issue 가 close 될 때까지 OPEN 유지하고 마지막 sub-issue PR 에서 함께 close - -#### Why - -- 작업 진입 전 사용자와 scope 합의가 강제됨 → 작업 도중 방향 이탈 / scope creep 회피 -- ad-hoc 으로 PR 직전에 이슈 만드는 패턴 차단 (closing reference 가 필요해서 PR 직전 즉흥 sub-issue 생성하는 안티 패턴) -- 메인 이슈와 sub-issue 의 계층 관계가 GitHub 상에서 명확히 link - -#### 예외 - -- 사용자가 명시적으로 **"이슈 없이 진행해"** / **"단발 hotfix"** 라고 지시한 경우 -- 1줄 typo 수정 / 명백한 작은 chore (사용자 동의 없이 진행해도 손실 적음 — 단, PR 타이틀 규약 준수를 위해 작업 시작 전 이슈 생성) - -#### 판단 모호 시 - -규모가 작아 보이더라도 **이슈 1개 생성** — 작업 끝난 후 PR 본문 정리할 때 추가 비용 거의 없음. -"이거 큰가?" 가 50/50 이면 **메인 + sub-issue 분할 쪽** 으로 보수 분류. - -#### Sub-issue 등록 명령 - -```bash -# 메인 이슈에 sub-issue 등록 (Relation 자동 활성화) -MAIN_ID=$(gh issue view --json id --jq .id) -SUB_ID=$(gh issue view --json id --jq .id) - -gh api graphql -f query=' -mutation($issueId: ID!, $subIssueId: ID!) { - addSubIssue(input: {issueId: $issueId, subIssueId: $subIssueId}) { - issue { number } - subIssue { number } - } -}' -f issueId="$MAIN_ID" -f subIssueId="$SUB_ID" -``` +| 구 규약 | 내용 | 공통 하네스 (`~/.claude/rules/`) | 본 프로젝트 전용 (아래 절) | +|---|---|---|---| +| 1 | 이슈 먼저 · sub-issue 분할 | `01-workflow.md` 1절, `03-conventions.md` Sub-issue 연결 | — | +| 2 | 자율 진행 · 예외 4영역 | `01-workflow.md` 2절 | 자율 영역 추가 항목 | +| 3 | Commit-per-TODO | `01-workflow.md` 3절 | 노트북 커밋 | +| 4 | PR 자동 생성 · 생성 후 피드백 | `01-workflow.md` 4절, `06-pr-feedback.md` | 도구 · `loop.md` 의 위치 | +| 5 | 권한 최소화 | `01-workflow.md` 5절 | Python 의존성 | +| 6 | Label · Issue Type · 접두사 3분리 | `03-conventions.md` | `scripts/gh-meta.sh` | +| — | 결정 기록 (ADR) | `07-decisions.md` | 저장 위치 (아래) | +| — | 오케스트레이션 · 역할 군 · 티어 | `02-orchestration.md`, 역할 정의 `~/.claude/agents/` | PR 작업 분배 표 |
-### 2. 자율 진행 정책 — 승인 요청 최소화 - -쿼리의 의도가 명확하면 AI 는 **사용자 승인 없이 진행** 한다. -> **핵심 원칙 1**: 아래 "자율 진행 영역"에 해당하는 작업은 **절대 사용자 확인을 요청하지 않는다.** -> 스크립트 실행, 파일 수정, 커밋, 브랜치 생성 등은 묻지 않고 즉시 실행한다. -> 이미 허용된 도구(`Bash`, `Edit`, `Write`, `gh`, `git`, `make` 등)는 추가 승인 없이 사용한다. -> **핵심 원칙 2**: 최대한 자율적으로 진행하되, "예외 영역"에 해당하는 작업은 반드시 사용자 확인을 받는다. -다음 4가지 영역만 예외로 -사용자 확인을 받는다: - -#### 예외 영역 (반드시 사용자 확인) - -| 영역 | 예시 | -|---|---| -| **시스템 자체 변경** | OS / 패키지 / 글로벌 환경 변경 (`apt-get install`, `sudo systemctl`, 시스템 서비스 enable 등) | -| **언급 없는 destructive 권한** | `git push --force`, branch 삭제, DB `DROP TABLE`, `git reset --hard`, 무인 PR merge | -| **외부 시스템 영향** | PR merge / issue close / 배포 트리거 / 외부 API 비용 결제 / 외부 DM 발송 | -| **모호한 작업 범위** | 사용자 의도가 다중 해석 가능하거나 scope 가 불명확한 경우 — 진행 전 구체화 질문 | - -#### 자율 진행 영역 (승인 불필요 — 즉시 실행) +## 규약 2 — 자율 진행 영역 추가 항목 -- 코드 작성 / 수정 / 리팩토링 / 삭제 -- 테스트 추가 / 갱신 -- 새 파일 / 디렉토리 생성 -- DB migration 작성 (단 `DROP` 류는 예외 — 위 destructive 영역) -- 의존성 추가 (`pip install` / `pyproject.toml` 갱신) — 단 신규 외부 패키지는 규약 5 적용 -- Branch 생성, 정상 push (force-push 아닌) -- Commit 단위 결정 및 실행 -- PR 본문 작성 -- **`scripts/` 하위 스크립트 실행** — 프로젝트 도구는 경로 확인 없이 실행 -- **이슈 / PR Label · Type 부여** — `scripts/gh-meta.sh` 활용, 별도 승인 불필요 -- **lint / fmt / test** — `make` 또는 `scripts/lint.sh` (ruff + nbqa) 실행, 경로 확인 불필요 +공통 목록에 더해 다음도 확인 없이 한다: -#### 판단 모호 시 -\"이게 destructive 영역인가?\" 가 50/50 이면 **사용자 확인 쪽으로 보수 분류**. 단, -이미 자율 진행 영역으로 열거된 항목은 50/50 이 아니다 — 확인 없이 진행한다. +- `scripts/` 하위 도구 실행, `make` · `scripts/lint.sh` (ruff + nbqa) 실행. +- 의존성 추가 (`pyproject.toml` 갱신, `uv`) — 단 신규 외부 패키지는 사전 확인 (규약 5). +- 노트북 출력 셀 정리 `make nb-clean`.
-### 3. Commit-per-TODO 정책 +## 규약 3 — 노트북 커밋 -별다른 사용자 언급이 없으면, AI 는 작업을 **논리적 변경 단위 (TODO)** 마다 commit 한다. - -> **금지**: 작업을 모두 완료한 뒤 한 번에 몰아서 커밋하는 것은 **절대 허용하지 않는다.** -> 논리적 변경 단위가 완성되는 즉시 커밋한다. 커밋을 뒤로 미루지 않는다. - -#### 원칙 - -- 논리적 변경 단위 완성 → **즉시 커밋** (다음 단위 작업 시작 전) -- 큰 PR 도 reviewable diff 단위로 분할 commit -- 각 commit 메시지는 [06-code-style.md](06-code-style.md) 의 컨벤션 준수: - - **Prefix 는 다섯 가지 중 택 1**: `[FEAT]:` / `[FIX]:` / `[REFAC]:` / `[DOCS]:` / `[CHORE]:` - - 이후 한국어 + 변경 의도 - - 단일 commit 이 너무 큰 변경을 담지 않도록 -- 빌드 그린 유지 — 각 commit 이 컴파일 + 테스트 통과 가능한 상태 - -#### 잘못된 패턴 (금지) - -```text -# BAD — 작업 완료 후 모아서 한 번에 커밋 -[파일 A 수정] → [파일 B 수정] → [파일 C 수정] → 커밋 하나로 묶음 -``` - -#### 올바른 패턴 - -```text -# GOOD — 논리 단위마다 즉시 커밋 -[파일 A 수정 — 기능 X 구현] → 커밋 -[파일 B 수정 — 기능 Y 구현] → 커밋 -[파일 C 수정 — 테스트 추가] → 커밋 -``` - -#### 예외 - -- 사용자가 명시적으로 \"한 번에 묶어줘\" / \"squash 해줘\" 요청 시 단일 commit -- 사용자가 \"단일 fix 만 해줘\" 등 명백한 단일 변경을 지시한 경우 - -#### 예시 - -```bash -git log --oneline (가상의 feature/#15 PR commit 시퀀스) -a1b2c3d [DOCS]: GraphEncoder docstring 추가 (en+ko) -e4f5g6h [FEAT]: GCN baseline forward 단위 테스트 추가 -i7j8k9l [FEAT]: GraphEncoder 구현 — in/hidden/out dim 설정 -m0n1o2p [REFAC]: TrainConfig 를 frozen dataclass 로 변경 -q3r4s5t [CHORE]: pyproject.toml ruff 규칙 ICN001 추가 -``` +- 노트북 (`.ipynb`) 은 **`make nb-clean` 후 커밋** 한다. 출력 셀이 diff 를 폭주시킨다. +- 로직은 `src/graphlm/`, 실험 흐름은 `notebooks/` — 한 커밋에 둘을 섞지 않는다 ([01-architecture.md](01-architecture.md)).
-### 4. PR 자동 생성 정책 - -작업 완료 직후 (별다른 언급 없으면) AI 는 **PR 을 자동 생성** 한다. - -#### 컨벤션 + 템플릿 준수 - -- **PR 타이틀**: `[카테고리#이슈번호] 제목` 정규식 (CI 강제) -- **본문**: [.github/PULL_REQUEST_TEMPLATE.md](../../.github/PULL_REQUEST_TEMPLATE.md) 의 모든 섹션 채움 - - 연관 이슈 (`Closes #N` — closing reference 명시) - - 구현 내용 - - CI / 머지 게이트 점검 - - 변경 영향 범위 + 위험도 - - 롤백 계획 -- **이슈 링크**: PR 본문 또는 Development sidebar 에 closing reference -- **Label 부여 필수**: 규약 6 매핑 표에 따라 PR 에도 동일 label 부여 (`gh pr create --label