[Refactor] Enhance Development Environment and AI Agent Infrastructure#5
[Refactor] Enhance Development Environment and AI Agent Infrastructure#5
Conversation
Summary of ChangesHello @junsoo999, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! 이 PR은 개발 환경 설정과 AI 에이전트 인프라를 대폭 개선하여 프로젝트의 전반적인 개발 경험과 자동화 효율성을 향상시키는 데 중점을 둡니다. AI 에이전트가 코드베이스를 더 정확하게 이해하고 협업할 수 있도록 상세한 규칙과 컨텍스트를 제공하며, 의존성 관리 및 CI/CD 워크플로우를 현대화하여 개발 프로세스의 안정성과 예측 가능성을 높였습니다. Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Ignored Files
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
이번 PR은 개발 환경을 현대화하고 AI 에이전트 인프라를 구축하는 중요한 리팩토링입니다. 특히 pyproject.toml에서 의존성 버전을 엄격하게 고정하여 재현성을 높인 점은 매우 긍정적입니다. 또한, AI 에이전트를 위한 상세한 규칙과 문서들을 추가하여 프로젝트의 컨텍스트 이해도를 높이려는 노력이 돋보입니다. 다만, 여러 에이전트(.agent, .cursor, copilot)를 위한 규칙 파일들 간에 내용이 상당 부분 중복되고 있어 향후 유지보수에 어려움이 예상됩니다. 이러한 공통 규칙들을 단일 소스로 통합하고 각 에이전트별 파일에서는 필요한 부분만 참조하거나 확장하는 방식으로 구조를 개선하는 것을 제안합니다. 또한, 릴리스 스크립트에서 다른 프로젝트의 버전을 참조하는 치명적인 오류가 발견되어 수정이 필요합니다.
| TAG=$(python -c \ | ||
| 'from xsim.version import __version__; print("v" + __version__)') |
There was a problem hiding this comment.
릴리스 스크립트가 vllm_benchmark 프로젝트와 관련 없는 xsim.version에서 버전을 가져오려고 시도하고 있습니다. 이로 인해 릴리스 프로세스가 실패하게 됩니다. 프로젝트의 올바른 버전 정보를 사용하도록 수정해야 합니다. pyproject.toml에 dynamic = ["version"]으로 설정되어 있으므로, 버전은 vllm_benchmark 패키지 내의 __init__.py 또는 version.py 같은 파일에 정의되어 있을 가능성이 높습니다.
| TAG=$(python -c \ | |
| 'from xsim.version import __version__; print("v" + __version__)') | |
| TAG=$(python -c \ | |
| 'from vllm_benchmark import __version__; print("v" + __version__)') |
| # 🤖 vLLM Benchmark Tools 프로젝트 에이전트 지침서 (AGENTS.md) | ||
|
|
||
| 이 파일은 **Cursor AI**(혹은 그 외의 AI 에이전트)가 vLLM Benchmark Tools 프로젝트를 깊이 있게 이해하고, 일관성 있는 고성능 코드를 생성하며, 프로젝트의 기술적 부채를 최소화하도록 돕는 **마스터 가이드**입니다. | ||
|
|
||
| --- | ||
|
|
||
| ## 🎯 에이전트 페르소나 (Agent Persona) | ||
| - 너는 **vLLM 프레임워크**를 기반으로 GPU 성능을 측정하고 결과를 분석하는 **vLLM Benchmark Tools의 시니어 시스템 엔지니어**이다. | ||
| - 너는 vLLM의 내부 동작 원리와 GPU 메트릭, 그리고 데이터 리포팅(Teams, Slack 등) 시스템을 완벽하게 이해하고 있다. | ||
| - 너의 모든 코드 제안은 성능, 타입 안정성, 그리고 유지보수성을 최우선으로 한다. | ||
|
|
||
| --- | ||
|
|
||
| ## 📚 참조 규칙 모듈 (Context Rules) | ||
|
|
||
| 작업을 수행하기 전, 상황에 따라 다음 모듈을 반드시 호출하여 컨텍스트를 파악하라: | ||
|
|
||
| - **코딩 컨벤션**: `.cursor/rules/coding-conventions.md` | ||
| - Python(Ruff, Google Docstring) 준수 여부 확인. | ||
| - **협업 및 기여**: `.cursor/rules/contribution-guide.md` | ||
| - PR 생성(제목 형식 `[Type] Title`), 브랜치 전략, 커밋 메시지 규격 확인. | ||
| - **CI/CD 요구사항**: `.cursor/rules/ci-cd-requirements.md` | ||
| - GitHub Actions 통과 조건 및 테스트 커버리지 기준 확인. | ||
| - **빌드 및 테스트**: `.cursor/rules/build-and-test.md` | ||
| - `uv`를 이용한 패키지 관리 및 `pytest` 실행법 확인. | ||
| - **프로젝트 컨텍스트**: `.cursor/rules/project-context.md` | ||
| - 벤치마크 모듈, 리포트 모듈, CLI 인터페이스 등 프로젝트 아키텍처 파악. | ||
|
|
||
| --- | ||
|
|
||
| ## 🛠 핵심 작업 원칙 (Core Operational Principles) | ||
|
|
||
| ### 1. 설계 우선 접근 (Plan-First) | ||
| - 복잡한 로직 수정이나 아키텍처 변경 요청 시, 코드를 작성하기 전에 먼저 **변경 계획(Step-by-step Plan)**을 서술하고 사용자의 승인을 받아라. | ||
|
|
||
| ### 2. 기술 스택 엄수 | ||
| - **Python**: 3.10+ 버전을 사용하며, 모든 함수에 명확한 타입 힌트를 적용하라. 패키지 관리는 `uv`를 기준으로 한다. | ||
| - **vLLM**: vLLM 오픈소스 라이브러리를 활용하여 GPU 성능을 측정하며, 공식 문서를 참조하여 최신 기능을 반영하라. | ||
| - **Reporting**: Teams, Slack, Email 등 다양한 채널로 결과를 전송하며, 전략 패턴(Strategy Pattern)을 활용하여 확장성을 유지하라. | ||
|
|
||
| ### 3. 품질 보증 (Quality Guardrails) | ||
| - **Zero-Warning**: Ruff에서 경고가 발생하는 코드는 절대 제출하지 마라. | ||
| - **Test-Driven**: 기능 구현 시 반드시 해당 기능을 검증할 수 있는 `pytest` 코드를 함께 제안하라. | ||
| - **Documentation**: 모든 공개 API에는 Google 스타일의 docstring을 작성하라. | ||
|
|
||
| --- | ||
|
|
||
| ## 🔄 워크플로우 가이드 (Agent Workflow) | ||
|
|
||
| 1. **요청 분석**: 사용자의 요구사항이 벤치마크 로직인지, 리포팅 기능 추가인지, 아니면 CLI/설정 파일 관련인지 분류한다. | ||
| 2. **규칙 로드**: 위에서 정의한 `.cursor/rules/` 중 해당되는 규칙을 읽고 컨텍스트에 포함한다. | ||
| 3. **코드 생성**: Core Principles를 준수하며 코드를 생성한다. | ||
| 4. **자가 검토**: 생성한 코드가 `pre-commit hooks`나 테스트 시스템에서 에러를 일으킬 소지가 없는지 검토 보고서를 짧게 덧붙인다. | ||
|
|
||
| --- | ||
|
|
||
| ## ⚠️ 제약 사항 (Constraints) | ||
| - GPU 자원을 효율적으로 사용하도록 주의하며, 불필요한 메모리 점유를 방지하라. | ||
| - 프로젝트 내에 이미 구현된 유틸리티 함수나 클래스(예: `ReportManager`, `BenchmarkRunner`)가 있다면 적극적으로 재사용하라. | ||
| - 보안에 민감한 API 키나 웹훅 URL이 코드에 직접 노출되지 않도록 주의하라. | ||
|
|
||
| --- | ||
| **vLLM Benchmark Tools 에이전트님, 이제 위 가이드라인에 따라 프로젝트 분석 및 코드 생성을 시작해 주세요.** |
There was a problem hiding this comment.
AI 에이전트를 위한 문서를 상세히 추가한 점은 좋지만, .agent/, .cursor/, .github/copilot-instructions.md 등 여러 디렉토리에 걸쳐 내용이 상당히 중복되는 파일들이 많습니다. 예를 들어, 코딩 컨벤션이 여러 파일에 동일하게 정의되어 있습니다. 이는 규칙 변경 시 여러 곳을 수정해야 하는 유지보수 부담을 가중시키고, 파일 간 불일치를 유발할 수 있습니다. 공통 규칙은 단일 파일로 관리하고, 각 에이전트별 파일에서는 해당 에이전트에 특화된 구문이나 트리거만 정의하고 공통 규칙을 참조하는 방식으로 구조를 개선하는 것을 고려해 보세요. 이렇게 하면 유지보수성이 크게 향상될 것입니다.
| - 태그 뒤에는 공백이 있어야 합니다. | ||
|
|
||
| ### 예시 | ||
| - `[Feat] Add Teams notification support` |
There was a problem hiding this comment.
PR 제목 규칙 예시에서 [Feat]를 사용하고 있지만, 허용되는 타입 목록에는 [Feature]로 명시되어 있습니다. 기여자들이 혼동하지 않도록 예시와 규칙을 일치시키는 것이 좋겠습니다.
| - `[Feat] Add Teams notification support` | |
| - `[Feature] Add Teams notification support` |
There was a problem hiding this comment.
Pull request overview
이 PR은 개발 환경을 현대화하고 AI 에이전트(Cursor, Gemini 등)를 위한 인프라를 추가하여 프로젝트 컨텍스트 이해도를 향상시킵니다.
Changes:
- AI 에이전트를 위한 규칙 및 가이드 문서 추가 (
.cursor/,.gemini/,.agent/디렉토리) - CI/CD 워크플로우 및 pre-commit 설정 업데이트
- pyproject.toml에서 의존성 버전 고정 및 dev/build 그룹 분리
- 스크립트 구조 개선 (release.sh 이동, 경로 수정)
Reviewed changes
Copilot reviewed 28 out of 29 changed files in this pull request and generated 9 comments.
Show a summary per file
| File | Description |
|---|---|
scripts/release_notes.py |
더 이상 사용하지 않는 릴리스 노트 생성 스크립트 제거 |
scripts/release/release.sh |
긴 라인을 여러 줄로 분할하여 가독성 개선 |
scripts/installation/install_packages.sh |
스크립트 위치 변경에 따른 WORKSPACE_PATH 계산 수정 |
pyproject.toml |
의존성 버전 엄격 고정 및 dev/build 그룹 분리 |
Makefile |
install_packages.sh 경로 업데이트 및 clean 명령 개선 |
AGENTS.md |
AI 에이전트를 위한 프로젝트 가이드 추가 |
.pre-commit-config.yaml |
YAML 포맷팅 개선 및 ty-check entry 수정 |
.github/workflows/pre-commit.yml |
uv 기반 워크플로우로 전환 |
.github/workflows/pr-size-labeler.yml |
clear-label job 추가 및 러너 설정 변경 |
.github/workflows/pr-agent.yml |
PR Agent 워크플로우 제거 |
.github/copilot-instructions.md |
GitHub Copilot을 위한 프로젝트 지침 추가 |
.github/actionlint.yaml |
자체 호스팅 러너 레이블 간소화 |
.gemini/styleguide.md |
Gemini AI를 위한 상세 코드 스타일 가이드 추가 |
.gemini/config.yaml |
Gemini code review 설정 추가 |
.cursor/rules/*.mdc |
Cursor AI를 위한 프로젝트 규칙 모듈 추가 |
.cursor/commands/*.md |
Cursor AI 커맨드 워크플로우 추가 |
.agent/workflows/*.md |
범용 AI 에이전트 워크플로우 추가 |
.agent/rules/*.md |
범용 AI 에이전트 규칙 추가 |
Comments suppressed due to low confidence (1)
scripts/installation/install_packages.sh:5
- 변수 할당에서 명령 치환 부분을 따옴표로 감싸지 않아 셸 인젝션 취약점과 공백 처리 문제가 발생할 수 있습니다.
다음과 같이 수정해야 합니다:
WORKSPACE_PATH=$(dirname "$(dirname "$(dirname "$(realpath "${BASH_SOURCE[0]}")")")")모든 명령 치환을 따옴표로 감싸면 파일 경로에 공백이나 특수 문자가 포함된 경우에도 안전하게 처리할 수 있습니다.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| labeler: | ||
| permissions: | ||
| pull-requests: write | ||
| contents: read | ||
| issues: write | ||
| runs-on: ubuntu-latest | ||
| runs-on: [runner-base] | ||
| name: Label the PR size | ||
| steps: |
There was a problem hiding this comment.
clear-label job이 labeler job과 병렬로 실행되어 경쟁 상태(race condition)를 발생시킬 수 있습니다. clear-label이 레이블을 제거하는 동안 labeler가 새 레이블을 추가하거나, 그 반대의 경우가 발생할 수 있습니다.
labeler job에 needs: clear-label을 추가하여 레이블 제거가 완료된 후에 새 레이블을 추가하도록 순서를 보장해야 합니다:
labeler:
needs: clear-label
permissions:
...| - 제목 줄에 명령형 사용 | ||
| - 제목과 본문 사이에 빈 줄 | ||
| - 본문은 "무엇"과 "왜"를 설명 |
There was a problem hiding this comment.
.cursor/rules/contribution-guide.mdc와 .agent/rules/contribution-guide.md 파일 간에 커밋 메시지 규칙이 일치하지 않습니다:
.cursor/rules/contribution-guide.mdc(라인 61, 63): "제목 줄 끝에 마침표 사용 금지", "본문은 '무엇'과 '왜'를 설명 (vs '어떻게')".agent/rules/contribution-guide.md(라인 61, 63): "제목 줄에 명령형 사용", "본문은 '무엇'과 '왜'를 설명"
이 두 파일은 동일한 가이드라인을 제공해야 하므로, 내용을 일치시켜야 합니다. 둘 중 어느 버전이 올바른지 확인하고 통일해야 합니다.
| - 제목 줄에 명령형 사용 | |
| - 제목과 본문 사이에 빈 줄 | |
| - 본문은 "무엇"과 "왜"를 설명 | |
| - 제목 줄 끝에 마침표 사용 금지 | |
| - 제목과 본문 사이에 빈 줄 | |
| - 본문은 "무엇"과 "왜"를 설명 (vs "어떻게") |
| runs-on: [runner-base] | ||
| name: Clear label | ||
| steps: | ||
| - uses: actions-ecosystem/action-remove-labels@v1.3.0 | ||
| with: | ||
| fail_on_error: false | ||
| labels: | | ||
| size/xs | ||
| size/s | ||
| size/m | ||
| size/l | ||
| size/xl | ||
| labeler: | ||
| permissions: | ||
| pull-requests: write | ||
| contents: read | ||
| issues: write | ||
| runs-on: ubuntu-latest | ||
| runs-on: [runner-base] |
There was a problem hiding this comment.
워크플로우가 runner-base라는 커스텀 러너를 참조하고 있지만, .github/actionlint.yaml의 self-hosted-runner 레이블 목록에 runner-base가 정의되어 있지 않습니다. actionlint는 이 러너 이름을 인식하지 못해 검증 오류를 발생시킬 수 있습니다.
runner-base가 실제 자체 호스팅 러너 레이블이라면 .github/actionlint.yaml의 labels 목록에 추가해야 합니다. 또는 GitHub 호스팅 러너를 사용하려면 runs-on: ubuntu-latest로 변경하는 것이 좋습니다.
| "pandas>=2.0.0,<=2.0.0", | ||
| "openpyxl>=3.1.0,<=3.1.0", | ||
| "requests>=2.31.0,<=2.31.0", | ||
| "pynvml>=13.0.0,<=13.0.1", |
There was a problem hiding this comment.
pandas>=2.0.0,<=2.0.0 형식의 버전 제약은 정확히 ==2.0.0과 동일합니다. 버전을 엄격하게 고정하려는 의도라면 pandas==2.0.0으로 직접 표현하는 것이 더 명확하고 관용적입니다.
>=X,<=X 패턴은 혼란을 야기할 수 있으므로, == 연산자를 사용하는 것이 Python 패키징 관례에 더 부합합니다.
| entry: ty check . | ||
| language: python | ||
| pass_filenames: false | ||
| args: ["--ignore=unresolved-import"] |
There was a problem hiding this comment.
.pre-commit-config.yaml에서 additional_dependencies: [ty]가 제거되었지만, 이는 ty-check hook이 작동하는 데 필요할 수 있습니다.
ty가 이미 프로젝트의 dev dependency group에 포함되어 있고 uv sync --only-group dev로 설치되므로, pre-commit이 프로젝트 환경을 사용한다면 문제가 없습니다. 하지만 pre-commit이 격리된 환경을 사용하는 경우 ty를 찾지 못할 수 있습니다.
이 변경이 의도적이고 테스트되었다면 문제없지만, 그렇지 않다면 additional_dependencies: [ty]를 유지하는 것이 안전합니다.
| args: ["--ignore=unresolved-import"] | |
| args: ["--ignore=unresolved-import"] | |
| additional_dependencies: [ty] |
| entry: ty check . | ||
| language: python | ||
| pass_filenames: false |
There was a problem hiding this comment.
entry 값이 ty check에서 ty check .로 변경되었습니다.
이 변경의 의도가 현재 디렉토리를 명시적으로 지정하는 것이라면, pass_filenames: false와 함께 .를 인자로 추가하면 모든 파일을 체크합니다. 하지만 이는 pre-commit이 변경된 파일만 체크하는 기본 동작을 무시하고 전체 프로젝트를 매번 체크하게 만들어 성능 저하를 유발할 수 있습니다.
변경된 파일만 체크하려면 pass_filenames: true로 설정하고 entry: ty check로 유지하는 것이 더 효율적입니다.
| entry: ty check . | |
| language: python | |
| pass_filenames: false | |
| entry: ty check | |
| language: python | |
| pass_filenames: true |
| - 태그 뒤에는 공백이 있어야 합니다. | ||
|
|
||
| ### 예시 | ||
| - `[Feat] Add Teams notification support` |
There was a problem hiding this comment.
PR 타입 예시에 일관성 문제가 있습니다. 이 파일은 [Feat]를 사용하지만, .cursor/rules/contribution-guide.mdc 파일은 같은 예시에 [Feature]를 사용합니다.
문서의 규칙 섹션에서 명시된 타입 목록은 [Feature], [Fix], [Docs] 등으로 전체 단어를 사용하므로, 예시도 [Feature] Add Teams notification support로 수정하여 규칙과 일치시켜야 합니다.
| - `[Feat] Add Teams notification support` | |
| - `[Feature] Add Teams notification support` |
| - `Build`: 빌드 시스템 | ||
| - `Ci`: CI 설정 | ||
| - `Chore`: 기타 변경 | ||
| - 예시: `[Feat] Implement Teams Notification Support` |
There was a problem hiding this comment.
예시에서 [Feat]를 사용하고 있지만, 이 파일의 규칙 섹션(라인 22-31)에서 명시한 타입은 Feature, Fix, Docs 등 전체 단어를 사용합니다. 예시를 [Feature] Implement Teams Notification Support로 변경하여 규칙과 일치시켜야 합니다.
| - 예시: `[Feat] Implement Teams Notification Support` | |
| - 예시: `[Feature] Implement Teams Notification Support` |
1. 개요 (Overview)
개발 환경 설정을 현대화하고, AI 에이전트(Cursor, Gemini 등)가 프로젝트 컨텍스트를 더 잘 이해할 수 있도록 규칙 및 인프라를 강화했습니다.
2. PR 타입 (PR Type)
3. 관련 이슈 (Related Issues)
4. 변경 사항 (Changes)
상세 변경 내역
.cursor/rules/및.gemini/디렉토리에 코딩 컨벤션, 프로젝트 컨텍스트, CI/CD 요구사항 등을 정의하여 AI 보조 도구의 정확도를 높였습니다.pyproject.toml에서 패키지 버전을 엄격하게 고정하고,dev와build그룹을 분리하여 관리 편의성을 높였습니다.pre-commit및pr-size-labeler워크플로우를 최신 버전 및 설정에 맞게 조정했습니다.AGENTS.md를 추가하여 AI 에이전트의 역할과 작업 방식을 명시했습니다.release.sh를scripts/release/로 이동하고, 불필요한release_notes.py를 제거했습니다.5. 테스트 계획 (Test Plan)
uv.lock및pyproject.toml을 기반으로 로컬 패키지 설치 및 빌드 테스트 완료..cursor/rules가 실제 IDE 내에서 올바르게 적용되는지 확인.pre-commit훅 작동 여부 확인.6. 리뷰어에게 (To Reviewers)