Skip to content

Commit a309abb

Browse files
kim-the9kim-the9
committed
feat: AGENTS.md 파일 추가 (프로젝트 구조 및 주요 흐름 문서화)
1 parent 3bf3876 commit a309abb

2 files changed

Lines changed: 187 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# PROJECT KNOWLEDGE BASE
2+
3+
**Generated:** 2026-01-16
4+
**Commit:** 3bf3876
5+
**Branch:** main
6+
7+
## OVERVIEW
8+
9+
ChatGPT-powered code review bot. Multi-deployment: GitHub Action, Probot app, AWS Lambda, Vercel Edge.
10+
11+
## STRUCTURE
12+
13+
```
14+
./
15+
├── src/ # Core logic (bot.ts, chat.ts)
16+
├── action/ # GitHub Action bundle (ncc output) - DO NOT EDIT
17+
├── dist/ # Probot/Vercel build output - DO NOT EDIT
18+
├── api/ # Vercel serverless entry
19+
├── test/ # Jest test fixtures
20+
├── action.yml # GitHub Action metadata → action/index.cjs
21+
├── serverless.yml # AWS Lambda config
22+
└── rollup.config.ts # Build orchestration
23+
```
24+
25+
## WHERE TO LOOK
26+
27+
| Task | Location | Notes |
28+
|------|----------|-------|
29+
| Code review logic | `src/bot.ts` | PR event handling, diff processing, file filtering |
30+
| OpenAI integration | `src/chat.ts` | Prompts, API calls, response parsing |
31+
| GitHub Action entry | `src/github-action.cjs` | Uses @probot/adapter-github-actions |
32+
| Probot standalone | `src/index.ts` | Standard Probot runner |
33+
| Vercel deployment | `api/github/webhooks/index.ts` | createNodeMiddleware wrapper |
34+
| AWS Lambda | `src/aws-lambda.cjs` | @probot/adapter-aws-lambda-serverless |
35+
36+
## BUILD & DEPLOY
37+
38+
```bash
39+
npm run build # rollup → dist/ + ncc → action/
40+
npm run start # Probot standalone (requires .env)
41+
npm test # Jest
42+
```
43+
44+
**Build outputs:**
45+
- `action/` → GitHub Action (action.yml points here)
46+
- `dist/` → Probot app, Vercel middleware
47+
- `lambda/` → AWS Lambda (via build:lambda)
48+
49+
## CONVENTIONS
50+
51+
### TypeScript
52+
- ESNext target, NodeNext module resolution
53+
- Strict mode enabled
54+
- Output to `lib/` (tsc) but builds use rollup/ncc
55+
56+
### Module System
57+
- ESM for source (`"type": "module"` in package.json)
58+
- CJS wrappers for Action/Lambda entry points (`.cjs` extension)
59+
- `.js` extension required in imports (`from "./chat.js"`)
60+
61+
### Environment Variables
62+
63+
| Variable | Purpose | Required |
64+
|----------|---------|----------|
65+
| `OPENAI_API_KEY` | OpenAI authentication | Yes |
66+
| `OPENAI_API_ENDPOINT` | Custom endpoint (default: api.openai.com) | No |
67+
| `AZURE_API_VERSION` | Azure OpenAI version | For Azure |
68+
| `AZURE_DEPLOYMENT` | Azure deployment name | For Azure |
69+
| `LANGUAGE` | Review output language | No |
70+
| `PROMPT` | Custom prompt prefix | No |
71+
| `MAX_PATCH_LENGTH` | Skip large diffs (default: Infinity) | No |
72+
| `MAX_CONTEXT_CHARS` | Truncate prompt context | No |
73+
| `IGNORE_PATTERNS` | Glob patterns to skip | No |
74+
| `INCLUDE_PATTERNS` | Glob patterns to include | No |
75+
| `TARGET_LABEL` | Only review labeled PRs | No |
76+
77+
## ANTI-PATTERNS (THIS PROJECT)
78+
79+
- **NEVER edit `action/`** - Generated by ncc, changes will be overwritten
80+
- **NEVER edit `dist/`** - Rollup output
81+
- Model hardcoded as `gpt-5-mini` in `src/chat.ts:246` - change there if needed
82+
- Response format uses `json_object` - prompts must include JSON output instructions
83+
84+
## UNIQUE STYLES
85+
86+
### Korean Comments
87+
- Source has Korean comments/prompts (코드 리뷰 시스템)
88+
- System prompts in `src/chat.ts` are Korean by default
89+
- `LANGUAGE` env var controls output language
90+
91+
### Incremental Review
92+
- On `synchronize` events, only reviews files changed in latest commit
93+
- Tracks previous review comments to avoid duplicate feedback
94+
95+
### File Relation Context
96+
- Extracts imports to provide related file context to AI
97+
- Relations: "imports", "imported-by", "same-dir"
98+
99+
## COMMANDS
100+
101+
```bash
102+
# Development
103+
npm install
104+
npm run build
105+
npm run start # Requires APP_ID, PRIVATE_KEY in .env
106+
107+
# Testing
108+
npm test
109+
110+
# Docker
111+
docker build -t cr-bot .
112+
docker run -e APP_ID=<id> -e PRIVATE_KEY=<pem> cr-bot
113+
```
114+
115+
## NOTES
116+
117+
- Uses Probot framework (v12) for GitHub integration
118+
- OpenAI SDK v4 with Azure support
119+
- PR file limit: 30 files max per review
120+
- Large patches (>MAX_PATCH_LENGTH) silently skipped
121+
- 422 errors from GitHub API trigger fallback to body-only review

‎src/AGENTS.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# src/ - Core Bot Logic
2+
3+
## OVERVIEW
4+
5+
Main application logic. 4 TypeScript files handling Probot events, OpenAI integration, and multi-platform entry points.
6+
7+
## FILES
8+
9+
| File | Purpose |
10+
|------|---------|
11+
| `bot.ts` | PR event handler, diff processing, review orchestration (786 lines) |
12+
| `chat.ts` | OpenAI/Azure client, prompts, JSON response parsing (355 lines) |
13+
| `index.ts` | Probot standalone entry |
14+
| `log.ts` | Logging setup |
15+
| `github-action.cjs` | GitHub Action adapter entry (CJS) |
16+
| `aws-lambda.cjs` | AWS Lambda adapter entry (CJS) |
17+
18+
## WHERE TO LOOK
19+
20+
| Task | File | Function/Section |
21+
|------|------|------------------|
22+
| Add PR event type | `bot.ts` | `app.on([...])` line 312 |
23+
| Modify review prompt | `chat.ts` | `generateSystemPrompt("review")` line 29 |
24+
| Modify summary prompt | `chat.ts` | `generateSystemPrompt("summary")` line 152 |
25+
| Change AI model | `chat.ts` | `callOpenAI()` line 246 |
26+
| Add file filter | `bot.ts` | `matchPatterns()` line 764 |
27+
| Adjust context budget | `bot.ts` | `MAX_CONTEXT_CHARS`, `MAX_GLOBAL_CONTEXT_CHARS` |
28+
29+
## KEY FLOWS
30+
31+
### PR Review Flow (bot.ts)
32+
```
33+
Event → loadChat() → compareCommits() → filter files →
34+
for each file:
35+
→ fetchFileContent() → findRelatedFiles() → buildReviewInput()
36+
→ chat.codeReview() → createReview()
37+
```
38+
39+
### OpenAI Call Flow (chat.ts)
40+
```
41+
codeReview(patch) → generatePrompt() → callOpenAI() → parse JSON → return {lgtm, comments[]}
42+
```
43+
44+
## CONVENTIONS
45+
46+
### Import Extensions
47+
All internal imports use `.js` extension (ESM requirement):
48+
```typescript
49+
import { Chat } from "./chat.js"; // NOT ./chat
50+
```
51+
52+
### Response Parsing
53+
Both `codeReview` and `summarizeChanges` expect JSON from OpenAI:
54+
- Use `response_format: { type: "json_object" }`
55+
- Parse with try/catch, fallback to raw content on failure
56+
57+
### Context Truncation
58+
Large content is truncated via `truncateForPrompt()`:
59+
- Keeps 60% head, 30% tail
60+
- Inserts `// --- truncated --- //` marker
61+
62+
## ANTI-PATTERNS
63+
64+
- **Don't add non-JSON prompts** - `response_format: json_object` requires JSON output instructions
65+
- **Don't exceed context budgets** - Use `allocateBudget()` helper for sections
66+
- **Don't modify CJS files** - `github-action.cjs`, `aws-lambda.cjs` are thin adapters only

0 commit comments

Comments
 (0)