[Chore] AI 협업 하네스(이슈/PR/Git 규칙) 구축 및 이슈 템플릿 오류 수정 (#5)#6
Conversation
- .github/ISSUE_TEMPLATE 내 name 필드 글자 수 충족으로 템플릿 오류 해결 - 루트 AGENTS.md 워크플로우 멘트 수정 및 스킬 4종 가이드라인 구축
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
✅ Files skipped from review due to trivial changes (1)
WalkthroughAGENTS.md에 이슈 기반 기본 워크플로우를 추가하고, issue/project/pull-request 관리 스킬 문서를 신설했으며, git-harness 규칙을 보강했습니다. 또한 CODEOWNERS를 추가하고 버그·작업 이슈 템플릿의 name과 title 기본값을 수정했습니다. ChangesAI 협업 규칙 문서화
저장소 설정 및 이슈 템플릿 수정
Estimated code review effort: 2 (Simple) | ~10 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
🚀 [AI Harness] 신설 스킬 모듈 작동 가이드 및 전체 워크플로우
이번 PR을 통해 토닥운 프로젝트의 AI 협업 하네스(Harness)가 구축되었습니다. 도입 배경과 전체 작업 파이프라인 흐름, 각 스킬의 역할을 요약해 드립니다.
🎯 도입 배경 (Why)
토닥운 프로젝트는 GitHub Issues + Projects 보드를 중심으로 작업을 수립하고 진척도를 관리합니다. 사람 팀원이라면 자연스럽게 이슈를 만들고, 보드 상태를 갱신하고, 컨벤션에 맞춰 PR을 올리겠지만, AI는 이런 프로젝트 생태계의 맥락을 모르면 독단적으로 움직이게 됩니다.
이 하네스 문서들은 AI도 우리 팀의 프로젝트 관리 생태계 위에서 동일한 워크플로우를 밟도록 행동 규범을 정밀하게 깎아낸 것입니다. 구체적으로는:
- 작업 시작 전 반드시 깃허브 이슈를 수립하고 프로젝트 보드에 연동하도록 강제합니다.
- 이슈/PR 제목·라벨·템플릿 등 팀 컨벤션을 자동으로 준수하게 합니다.
- 사용자 승인 없이는 이슈/PR을 자의적으로 생성하거나 머지하지 못하도록 통제합니다.
- 결과적으로 AI가 만들어낸 산출물이 사람이 만든 것과 동일한 품질과 규격을 갖추게 됩니다.
🗺️ AI 자동화 파이프라인 (Issue-Driven Workflow)
새로 추가된 하네스 문서들에 의해 AI의 모든 작업은 아래의 시퀀스를 강제적으로 따르게 됩니다.
graph TD
A["👤 사용자 작업 요청"] --> B{"이슈 동기화 & 결재<br/>project-management"}
B -- "승인" --> C["템플릿/라벨 맞춤 이슈 생성<br/>issue-management"]
B -- "생략" --> D["브랜치 생성 & 개발 진행<br/>git-harness · project-structure"]
C --> D
D --> E["레이어 아키텍처 정합성 검증<br/>sync-and-validate.sh"]
E --> F["커밋 & 푸시<br/>git-harness · pre-push Hook · GitHub Ruleset"]
F --> G["Draft PR 자동 생성 (사용자 결재)<br/>pull-request-management"]
G --> H["AI 멀티라인 셀프 리뷰 코멘트 등록<br/>pull-request-management"]
H --> I["리뷰어 자동 배정 & 검토 대기<br/>.github/CODEOWNERS"]
🛠️ 신설된 핵심 스킬 상세 (What & How)
| 스킬 | 역할 | 작동 시점 |
|---|---|---|
project-management |
최상위 관제탑. 프로젝트 보드 연동 강제 및 자의적 행동 차단. | 작업 시작 시 무조건 우선 로드. 이슈/PR 생성 직전 사용자 결재 게이트 역할. |
issue-management |
이슈 생성 컨벤션 관리. 템플릿·라벨·담당자 규칙 적용. | 이슈 생성 승인이 떨어진 직후 로드. |
pull-request-management |
PR 규격 보장 및 셀프 리뷰 자동화. 멀티라인 인라인 코멘트 강제. | 커밋 완료 후 PR 생성 시 로드. |
git-harness |
안전한 히스토리 보호. Conventional Commits, 포스 푸시 차단. | Git 커밋·푸시·브랜치 이동 시 로드. |
| # YAPP 28th Team 2 iOS CODEOWNERS | ||
| # 모든 파일 변경 시 seungwone과 MoonGoon72를 리뷰어로 자동 지정합니다. | ||
| * @seungwone @MoonGoon72 |
There was a problem hiding this comment.
🤖 [AI Self-Review]
저장소 내 모든 파일의 변경 사항에 대해 두 분을 기본 리뷰어로 자동 지정하도록 깃허브 공식 룰을 신설했습니다.
앞으로 CLI나 깃허브 웹 어디서 PR을 올리든 리뷰어 누락이 발생하지 않습니다. 혹시 특정 도메인(폴더)마다 전담 리뷰어를 분리해야 할 경우 이 파일에 경로 룰을 추가하면 됩니다!
| --- | ||
| name: 작업 | ||
| name: 일반 작업 | ||
| about: 별도 티켓으로 정리된 작업을 GitHub Issue로 연결합니다. | ||
| title: "[Task] " | ||
| title: "[iOS] [Feat] " | ||
| labels: "" | ||
| assignees: "" | ||
| --- |
There was a problem hiding this comment.
🤖 [AI Self-Review]
기존 템플릿에 있던 [Task] 타입은 컨벤션에 없는 타입이므로, 일반 작업의 표준인 [Feat]로 통일시켰습니다.
또한, 모든 이슈에 공통적으로 붙어야 하는 [iOS] 플랫폼 헤더도 템플릿 자체에 고정하여 누락 휴먼 에러를 방지했습니다.
| ## 3. 라인 단위 셀프 인라인 코멘트(Inline Comment) 작성 규칙 (승인 후 진행)**: | ||
| AI는 PR 생성을 완료한 직후, 자의적으로 코멘트를 작성하지 않고 반드시 사용자에게 작성 동의 여부를 가볍게 질문하여 결정한다. | ||
| - **질문 템플릿**: `"Draft PR (#PR번호) 생성이 완료되었습니다. 수정한 코드 라인들에 대해 AI 셀프 코드 리뷰 인라인 코멘트를 작성해 둘까요? 아니면 바로 검토하시겠습니까?"` | ||
| - **사용자 승인(동의) 시**: | ||
| 자신이 수정한 코드 중 구조적으로 중요하거나 로직 설명이 필요한 부분, 혹은 사용자 및 리뷰어와의 조율이 필요한 특정 코드 라인에 대해 **셀프 인라인 코멘트(라인 단위 코멘트)를 작성**한다. | ||
| - **실행 방식 (GitHub API 호출)**: | ||
| `gh api`를 사용하여 해당 PR 번호에 셀프 리뷰 코멘트를 등록한다. | ||
| * **API 엔드포인트**: `POST /repos/{owner}/{repo}/pulls/{pull_number}/reviews` | ||
| * **요청 데이터 포맷**: | ||
| ```json | ||
| { | ||
| "body": "AI 1차 셀프 코드 리뷰 및 설명", | ||
| "event": "COMMENT", | ||
| "comments": [ | ||
| { | ||
| "path": "Projects/Feature/FortuneFeature/Sources/FortuneFeature.swift", | ||
| "start_line": 10, | ||
| "start_side": "RIGHT", | ||
| "line": 12, | ||
| "body": "여기에 수정한 이유, 핵심 디자인 패턴 또는 사용자에게 조언/논의할 내용을 적습니다. (단일 라인 작성 시에는 start_line과 start_side는 제외하고 line만 명시 가능)" | ||
| } | ||
| ] | ||
| } | ||
| ``` | ||
| - **거절 또는 생략 요청 시**: 인라인 코멘트 작성 작업을 생략하고 즉시 대기한다. |
There was a problem hiding this comment.
🤖 [AI Self-Review]
이 PR에 달리고 있는 지금 이 코멘트들처럼, 앞으로 AI가 PR을 생성할 때는 항상 핵심 코드 범위를 다중 지정하여 '스스로 리뷰 코멘트'를 달도록 하는 의무화 룰을 신설했습니다.
리뷰어분들이 AI의 코드 변경 의도를 파악하는 데 큰 도움이 될 것입니다.
seungwone
left a comment
seungwone
left a comment
There was a problem hiding this comment.
AI 1차 셀프 코드 리뷰 및 설명 - 2차 보완 분
| ### Default Workflow (Issue-Driven Development) | ||
| AI가 이 프로젝트 내에서 기능 추가, 버그 수정, 리팩토링 등의 작업을 진행할 때는 무조건 [project-management](./.agents/skills/project-management/SKILL.md) 스킬에 정의된 이슈 수립 및 보드 연동 흐름을 최우선으로 준수한다. | ||
|
|
||
| 요약 워크플로우 파이프라인: | ||
| - **작업 개시**: 이슈 조회 및 생성, 프로젝트 보드 연동 ➡️ [issue-management](./.agents/skills/issue-management/SKILL.md) | ||
| - **개발 진행**: 브랜치 생성 및 커밋 메시지 작성 ➡️ [git-harness](./.agents/skills/git-harness/SKILL.md) | ||
| - **작업 마무리**: PR 생성 및 본문 작성 ➡️ [pull-request-management](./.agents/skills/pull-request-management/SKILL.md) |
There was a problem hiding this comment.
🤖 [AI Self-Review]
이번에 신설된 핵심 AI 가이드라인(Harness)의 수명 주기를 AGENTS.md에 공식 등록하고 설명하는 섹션입니다.
- 이슈 수립 및 보드 연동:
project-management&issue-management스킬 - 코드 변경 및 깃 커밋/푸시:
git-harness스킬 - PR 생성 및 셀프 리뷰:
pull-request-management스킬
| - `project-management`: 이 프로젝트의 전반적인 작업 수립, 이슈 조회/생성 여부 질문 프로세스 및 프로젝트 보드 연동 시 무조건 참고함 (이슈 탐색, PR 닫기 연동 등) | ||
| - `issue-management`: 큰 요구사항을 하위 작업으로 쪼개고, 템플릿과 라벨에 맞춘 이슈 생성 규칙 (하위 이슈 분리, 템플릿 및 라벨 적용 등) | ||
| - `pull-request-management`: PR 템플릿 작성 규칙 및 UI 변경 시 스크린샷/WebP 파일 임베딩 지침 (PR 템플릿, 시각 자료 첨부 등) |
There was a problem hiding this comment.
🤖 [AI Self-Review]
이 프로젝트는 컨텍스트 토큰을 절약하기 위해 폴더나 파일 유형에 따라 이 룰들을 선택적으로 자동 로드하는 **하이브리드 모듈형 규칙(Hybrid Modular Rules)**으로 구동됩니다.
이번에 추가된 3대 핵심 스킬 모듈(project-management, issue-management, pull-request-management)이 폴더 규칙에 맞게 필요한 순간에만 동적으로 바인딩되도록 연결 설정을 완료했습니다.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.agents/skills/git-harness/SKILL.md:
- Line 16: The bullet-point example in the SKILL.md guidance uses a code span
containing a leading space, which triggers markdownlint MD038; update the
affected markdown example to remove the space inside the inline code so the
symbol is shown as `-` rather than `- `, keeping the wording in the same section
that describes body bullet formatting.
In @.agents/skills/pull-request-management/SKILL.md:
- Around line 21-33: The PR title/body rules in pull-request-management
currently force an issue number and Closes/Fixes everywhere, which conflicts
with the no-issue flow. Update the guidance in the scoped title format section
and the PR body automation section so the `(`#이슈번호`)` suffix and `Closes
`#이슈번호``/`Fixes `#이슈번호`` requirement apply only when an issue actually exists. Keep
the existing conventions aligned with issue-management, but add explicit
conditional wording for the issue-free path using the same PR guidance symbols
and template references.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 7a747b95-2039-495b-b99e-916f3799b41a
📒 Files selected for processing (8)
.agents/skills/git-harness/SKILL.md.agents/skills/issue-management/SKILL.md.agents/skills/project-management/SKILL.md.agents/skills/pull-request-management/SKILL.md.github/CODEOWNERS.github/ISSUE_TEMPLATE/bug.md.github/ISSUE_TEMPLATE/task.mdAGENTS.md
| * 예시: `[iOS] [Feat] [운세] 운세 UI 레이아웃 구현` (도메인 적용) | ||
| - **이슈 템플릿 준수 및 본문 생성**: | ||
| - 이슈 생성 시 로컬 저장소 내에 보관된 **`.github/ISSUE_TEMPLATE/`** 폴더 하위의 템플릿 마크다운 문서를 기반으로 본문을 빌드한다: | ||
| * **기능 개발/설정/기타 작업**: `task.md` 템플릿의 본문 서식을 채워 사용하고, 라벨은 **`enhancement`** 또는 **`documentation`**을 지정한다. (작업의 성격에 따라 두 라벨을 모두 지정하는 것도 가능하다.) |
There was a problem hiding this comment.
저희 라벨은 저 두 개만 사용하는걸까요? 지금 라벨은 레포지토리 만들 때 기본으로 생성된 라벨인걸로 아는데 저렇게 유지를 할 지 아니면, 타입과 대응되도록 라벨을 수정할지 논의해보면 좋을 것 같습니다.
There was a problem hiding this comment.
처음에는 이슈에 프로젝트를 연결한 뒤, 프로젝트의 Page 속성으로 화면 도메인을 지정해줄 수 있어, 라벨을 중복지정해 줄 필요는 없다고 생각했습니다!
그런데 지금보니 Page 속성은 프로젝트에만 노출되고 이슈탭에서는 따로 노출되지 않는 것 같네요...
또 생각해보니 Core, App, Tuist 등 공통 도메인은 Page 속성에 들어가지 않으니 따로 라벨이 필요할 것 같네요!
There was a problem hiding this comment.
`[Epic]`, `[Feat]`, `[Bug]`, `[Docs]`, `[Refactor]`, `[Chore]`
`[온보딩]`, `[운세]`, `[행운액션]`, `[토닥이]`, `[마이페이지]`
`[Core]`, `[App]`, `[Tuist]`
일단 이슈 스킬에 명시해둔 위 타입/도메인들을 라벨에 추가해두었습니다.
불필요하거나 추가가 필요해 보이는 라벨 있으시면 의견 남겨주세요!
There was a problem hiding this comment.
제 의도는 제목에 쓰는 타입/도메인을 모두 라벨로 복제하자는 것보다는, 기본 라벨인 enhancement, documentation, bug만으로는 [Feat], [Refactor], [Chore] 같은 작업 타입을 구분하기 애매해서 라벨 체계를 논의해보자는 쪽이었습니다!
화면 도메인은 제목의 [운세], [온보딩]과 프로젝트의 Page 필드로 이미 관리되고 있으니, 화면별 라벨까지 추가하면 중복 관리가 될 것 같습니다.
대신 라벨은 최소한의 필터링 기준으로만 두는 건 어떨까요?
- 타입 라벨:
feature,bug,docs,refactor,chore - 공통 영역 라벨:
core,app,tuist
특히 Core, App, Tuist처럼 Page 필드에 들어가지 않는 공통 도메인만 별도 라벨로 두면 이슈 탭에서도 필터링이 가능하고, 화면 도메인 라벨은 과하게 늘어나지 않을 것 같습니다.
There was a problem hiding this comment.
이슈는 프로젝트를 통해 관리하니 화면도메인 라벨을 추가해준다면 프로젝트의 Page 속성과 중복되어 헷갈릴 수 있겠네요, 확실히 이슈는 Page 속성만으로 관리하는게 좋아보입니다!
그런데 현재 PR은 프로젝트 보드에서 이슈와 중복 등록되는 경우를 막기 위해 의도적으로 프로젝트와 연결을 해주지 않고 있는데, 그래서 PR에는 Page 속성을 지정해 줄 수가 없는 상태입니다.
그래서 도메인 라벨을 붙여줄까 했는데... 생각해보니 PR을 프로젝트에 연동해도 필터를 통해 이슈만 파악할 수 있어 큰 문제는 없을거 같네요 이 방식 괜찮으신가요?
epic 템플릿은 삭제하도록 하겠습니다!
There was a problem hiding this comment.
아 이해했습니다! PR은 프로젝트 보드와 중복으로 인해서 라벨을 통해 관리하고자 하셨던 거군요.
저도 원래 의도대로 PR을 프로젝트에 연동하면 기존에 정한 프로젝트 보드를 이슈 중심으로 관리하는 것이 흐려지고 중복이 발생할 수 있을 것 같습니다.
제가 처음에 말씀드린 라벨 관련 코멘트는 화면 도메인을 라벨로 복제하자는 의도보다는, 기본 라벨인 enhancement, documentation, bug만 사용할 때 [Feat], [Refactor], [Chore] 같은 작업 타입이 모두 enhancement로 묶이는 게 괜찮은지 논의해보자는 취지였습니다.
도메인은 이슈의 경우 프로젝트 Page 속성으로 관리하고, PR은 제목의 [도메인]과 연결된 이슈 번호로 식별하는 방식이 더 깔끔해 보입니다.
그래서 라벨은 우선 enhancement, bug, documentation처럼 큰 분류만 유지해도 괜찮을 것 같습니다. 다만 이후 이슈/PR을 타입별로 더 세밀하게 필터링할 필요가 생기면 feature, refactor, chore 같은 타입 라벨을 추가하는 방향으로 확장하면 좋을 것 같은데 어떠신가요?
There was a problem hiding this comment.
넵! 제목에 자세한 타입을 명시하도록 컨벤션을 유지하고 있으니 라벨은 큰 분류로만 분류해도 괜찮을 것 같네요.
지금은 enhancement, bug, documentation 등 큰 분류만 유지하고 필요한 경우 확장하는 방향으로 가시죠!
There was a problem hiding this comment.
좋습니다! 이제 그럼 해당 PR은 머지 부탁드립니다!
|
수고하셨습니다! 리뷰 확인 후 논의 나눠보면 좋을 것 같습니다! |
Co-authored-by: MoonGoon <moongoon.cnu@gmail.com>
2 participants
변경 내용
.github/ISSUE_TEMPLATE내 버그/태스크 템플릿name필드를 3글자 이상으로 수정하여 이슈 생성 시 발생하던 웹 UI 파싱 오류를 해결했습니다.AGENTS.md지침을 개정하고, 하위 모듈형 스킬 4종(issue,pr,git,project-management)을 설계 및 구축했습니다.고민한 내용
스크린샷
해당 없음 (UI 변경과 무관한 환경 설정 및 가이드라인 작업)
테스트
./scripts/sync-and-validate.sh로컬 아키텍처 정합성 검사 통과 완료pre-push hook)을 통한 아키텍처 멱등성 검증 정상 통과 확인 완료참고 사항
체크리스트
Summary by CodeRabbit