Skip to content

Commit b46613b

Browse files
JwhyeeJwhyee
committed
docs(be): Gemini CLI 프로젝트 가이드라인 및 문서 추가
1 parent 48432ec commit b46613b

4 files changed

Lines changed: 141 additions & 0 deletions

File tree

‎.gemini/docs/DOCUMENT.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Project Planning
2+
The objective of this project is to provide automated, high-quality code reviews for GitHub Pull Requests using Google's Gemini AI. By integrating directly with GitHub Webhooks, the system can automatically analyze incoming code changes and provide immediate feedback, reducing the burden on human reviewers and maintaining high code quality.
3+
4+
# Core Logic & Mechanisms
5+
The system operates through a series of orchestrated steps:
6+
1. **Webhook Reception**: A Spring Boot controller (`CodeReviewController`) receives payloads from GitHub for specific events (e.g., `pull_request`).
7+
2. **Signature Verification**: The system validates the `X-Hub-Signature-256` header against a shared secret to ensure authenticity.
8+
3. **Event Orchestration**: `CodeReviewFacade` determines the appropriate action based on the GitHub event type.
9+
4. **Review Processing**:
10+
* The system extracts code diffs and contexts for review.
11+
* `CodeReviewService` filters and prioritizes files to review (handling limits and concurrency).
12+
* Each relevant hunk is sent to `GoogleGeminiClient` with a structured prompt.
13+
5. **Feedback Loop**: Gemini's responses are parsed and posted as review comments on the GitHub Pull Request via `GithubReviewClient`.
14+
6. **Concurrency & Rate Limiting**: A `Semaphore` limits simultaneous AI calls, and a mandatory cooldown period is applied between calls to comply with API limits.
15+
16+
# Versioning
17+
- `v1.0.0 - 2026-03-10`: Initial foundational documentation and core review logic discovery.

‎.gemini/docs/PLANNING.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Execution Plan: Portfolio vs. Actual Code Alignment
2+
3+
## 1. Goal
4+
Identify and document discrepancies between the portfolio description (`AiCodeReviewSection.tsx`) and the actual implementation in `src/`, then generate a `SOLUTION.md` file to suggest corrections.
5+
6+
## 2. Scope
7+
### In-Scope
8+
- Comparison of technical patterns (Facade, Queue, Rate Limiting, Security) mentioned in the portfolio with the actual Kotlin source code.
9+
- Verification of code snippets in the portfolio against the actual implementation.
10+
- Identifying exaggerated or non-existent features (e.g., DB-based Job Queue with SKIP LOCKED).
11+
- Creating `.gemini/docs/SOLUTION.md` with structured findings.
12+
13+
### Out-of-Scope
14+
- Modifying `AiCodeReviewSection.tsx` or any actual source code.
15+
- Implementing the missing features (like the DB Job Queue).
16+
- Verifying external blog links.
17+
18+
## 3. Architecture Impact
19+
```
20+
.gemini/docs/
21+
└── SOLUTION.md (To be created)
22+
```
23+
24+
## 4. Execution Plan
25+
### Phase 1: Preparation & Analysis
26+
- [x] Read `.gemini/docs/STRUCTURE.md` to understand architecture.
27+
- [x] Read `.gemini/docs/AiCodeReviewSection.tsx` to identify claims.
28+
- [x] Browse and read key source files (`ReviewJobQueue.kt`, `CodeReviewService.kt`, `GithubSignature.kt`, `GithubAppTokenProvider.kt`).
29+
30+
### Phase 2: Discrepancy Identification
31+
- [x] Cross-reference "DB Pessimistic Lock" claim with `ReviewJobQueue.kt` and `domain/repository`.
32+
- [x] Cross-reference "GeminiRateLimiter" component claim with `CodeReviewService.kt`.
33+
- [x] Cross-reference "Constant-Time Comparison" claim with `GithubSignature.kt`.
34+
- [x] Cross-reference "JJWT RS256" claim with `GithubAppTokenProvider.kt`.
35+
- [x] Cross-reference "Facade Pattern" claim with actual routing/handler structure.
36+
- [x] Cross-reference "Producer-Consumer / Coroutine Channel" claim with actual queue implementation.
37+
- [x] Evaluate metrics (0% 429 error rate) based on the current `cooldownAfterCall` logic.
38+
39+
### Phase 3: Documentation
40+
- [x] Generate `.gemini/docs/SOLUTION.md` with the required format for each discrepancy.
41+
42+
## 5. Risk Mitigation
43+
- **Potential Breaking Changes**: None (Analysis only).
44+
- **Rollback Strategy**: Delete `SOLUTION.md` if needed.
45+
46+
## 6. Final Verification Wave
47+
- [x] Run `./gradlew test` (to ensure the project is in a valid state, though we are not changing code).
48+
- [x] Verify the content of `.gemini/docs/SOLUTION.md` matches the user's requested format.
49+
- [x] Manual Spot Check: Ensure all discrepancies found are grounded in the actual code.

‎.gemini/docs/STRUCTURE.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# OVERVIEW
2+
An AI-powered automated code review system designed to integrate with GitHub Pull Requests. Built with Kotlin and Spring Boot, it utilizes Google Gemini AI to analyze code changes and provide automated feedback directly on GitHub.
3+
4+
# STRUCTURE
5+
```
6+
.
7+
├── .github/workflows/ # CI/CD pipelines (GitHub Actions)
8+
├── src/
9+
│ ├── main/
10+
│ │ ├── kotlin/com/project/codereview/
11+
│ │ │ ├── application/ # Configuration and utility classes
12+
│ │ │ ├── client/ # External API clients (GitHub, Google Gemini)
13+
│ │ │ ├── core/ # Core business logic, controllers, and services
14+
│ │ │ ├── domain/ # Domain models and repository interfaces
15+
│ │ │ └── CodeReviewApplication.kt # Main entry point
16+
│ │ └── resources/ # Application properties and static assets
17+
│ └── test/ # Unit and integration tests
18+
├── build.gradle.kts # Build configuration
19+
└── Dockerfile # Containerization configuration
20+
```
21+
22+
# WHERE TO LOOK
23+
| Task / Workflow | Exact File Path |
24+
| :--- | :--- |
25+
| GitHub Webhook Entry Point | `src/main/kotlin/com/project/codereview/core/controller/CodeReviewController.kt` |
26+
| Event Handling Orchestration | `src/main/kotlin/com/project/codereview/core/service/CodeReviewFacade.kt` |
27+
| AI Review Logic | `src/main/kotlin/com/project/codereview/core/service/CodeReviewService.kt` |
28+
| Gemini API Integration | `src/main/kotlin/com/project/codereview/client/google/GoogleGeminiClient.kt` |
29+
| GitHub API Integration | `src/main/kotlin/com/project/codereview/client/github/GithubReviewClient.kt` |
30+
| GitHub Diff Parsing | `src/main/kotlin/com/project/codereview/client/github/GithubDiffUtils.kt` |
31+
| Domain Models | `src/main/kotlin/com/project/codereview/domain/model/` |
32+
33+
# CODE MAP
34+
| Symbol | Type | Location |
35+
| :--- | :--- | :--- |
36+
| `CodeReviewController` | Class (RestController) | `src/main/kotlin/com/project/codereview/core/controller/CodeReviewController.kt` |
37+
| `CodeReviewFacade` | Class (Service) | `src/main/kotlin/com/project/codereview/core/service/CodeReviewFacade.kt` |
38+
| `CodeReviewService` | Class (Service) | `src/main/kotlin/com/project/codereview/core/service/CodeReviewService.kt` |
39+
| `GoogleGeminiClient` | Class (Service) | `src/main/kotlin/com/project/codereview/client/google/GoogleGeminiClient.kt` |
40+
| `GithubReviewClient` | Class (Service) | `src/main/kotlin/com/project/codereview/client/github/GithubReviewClient.kt` |
41+
| `GithubSignature` | Object (Utility) | `src/main/kotlin/com/project/codereview/core/util/GithubSignature.kt` |
42+
43+
# CONVENTIONS (THIS PROJECT)
44+
- **Kotlin Coroutines**: Extensive use of `suspend` functions and coroutine scopes for non-blocking I/O.
45+
- **Spring Boot 3.x**: Leverages the latest Spring Boot features and dependencies.
46+
- **GitHub App Auth**: Uses JWT (JJWT) for authenticating as a GitHub App.
47+
- **Signature Validation**: All incoming webhooks must be validated using `X-Hub-Signature-256`.
48+
- **Concurrency Control**: `Semaphore` is used in `CodeReviewService` to limit concurrent AI calls.
49+
- **Rate Limiting**: Implements a cooldown period (1 minute + jitter) after each Gemini call.
50+
51+
# ANTI-PATTERNS / TECH DEBT
52+
- **Hardcoded Limits**: Max review counts and concurrency limits are currently hardcoded in `CodeReviewService`.
53+
- **Error Handling**: Catch-all `Throwable` in some service methods; could be more specific.
54+
- **Payload Deserialization**: `FAIL_ON_UNKNOWN_PROPERTIES = false` is used, which helps with evolving APIs but might hide breaking changes.
55+
56+
# COMMANDS
57+
- **Build**: `./gradlew build`
58+
- **Test**: `./gradlew test`
59+
- **Run Locally**: `./gradlew bootRun`
60+
61+
# NOTES
62+
- The project relies on environment variables for GitHub secrets and Gemini API keys (see `application.yaml` for expected keys).

‎GEMINI.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Gemini CLI - Project Guidelines
2+
3+
## 0. Mandatory Document Rules
4+
- **ALWAYS** read `.gemini/docs/STRUCTURE.md` and `.gemini/docs/DOCUMENT.md` before starting any task.
5+
- **CONTINUOUSLY** update `STRUCTURE.md` and `DOCUMENT.md` as the project evolves or new information is discovered.
6+
- **APPEND-ONLY** for `DOCUMENT.md`: When updating `DOCUMENT.md` with new logic or planning, do not delete existing text. Apply a strikethrough (~~text~~) to outdated information and append the new information at the bottom.
7+
- **VERSION BUMP**: Always increment the version number in `DOCUMENT.md` when making updates, including the current date.
8+
9+
## Engineering Standards
10+
- Follow the established architecture: `core`, `domain`, `client`, `application`.
11+
- Maintain the use of Kotlin Coroutines for all asynchronous operations.
12+
- Ensure all new GitHub webhook events are properly validated for signatures.
13+
- Respect the concurrency and cooldown mechanisms in `CodeReviewService`.

0 commit comments

Comments
 (0)