에이전트 하네스와 협업 문서 추가

.agents/skills/README.md

@@ -0,0 +1,17 @@
+# Skills
+
+Reusable project skills for the FastAPI/Python AI service.
+
+- `api-design`: FastAPI route and schema design.
+- `database-schema`: Postgres schema guidance.
+- `docker`: Docker and Compose guidance.
+- `fastapi-python-arch`: Python/FastAPI architecture guidance.
+- `git-commit`: Logical local commits.
+- `migration-guide`: Alembic/schema migration guidance.
+- `planning`: Structured planning interview.
+- `pytest-guide`: Python test patterns.
+- `resolve-reviews`: GitHub PR review handling.
+- `security-checklist`: Security review checklist.
+- `systematic-debugging`: Root-cause debugging workflow.
+- `test`: Smallest useful test/check selection.
+- `write-pr`: Push and open PR.

.agents/skills/api-design/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: api-design
+description: FastAPI API design guide for routes, request/response schemas, status codes, and error behavior.
+---
+
+# FastAPI API Design
+
+Use this when adding or reviewing API endpoints.
+
+## Rules
+
+- Keep routes resource-oriented and versionable when a public contract exists.
+- Put request/response shapes in Pydantic models when they are reused or non-trivial.
+- Return explicit status codes for create/delete/error paths.
+- Keep external AI/provider calls behind a service function, not inside route handlers.
+- Do not change an API contract without updating matching docs or examples if they exist.
+
+## Checks
+
+```bash
+python -m py_compile main.py
+python -c "from main import app; assert app"
+```

.agents/skills/database-schema/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: database-schema
+description: Postgres schema guidance for this Python service. Use only when DB tables or persistence are actually being added.
+---
+
+# Database Schema Guide
+
+This repo currently has no application DB layer. Do not add schema tooling until a real persistence requirement exists.
+
+## Defaults When Needed
+
+- Postgres for local/dev parity.
+- Alembic for migrations if SQLAlchemy is introduced.
+- `snake_case` table and column names.
+- `created_at` and `updated_at` timestamps on durable domain tables.
+- Explicit indexes for frequent lookup predicates only.
+
+Keep schema changes in the same PR as the code that uses them.

.agents/skills/docker/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: docker
+description: Docker and Docker Compose guide for this FastAPI/Python service.
+---
+
+# Docker Guide
+
+Use the existing `compose.yml` before adding new Docker files.
+
+## Compose
+
+- Keep app containers out of dev compose unless explicitly requested.
+- Prefer official images with pinned tags.
+- Add healthchecks for stateful services.
+- Use volumes only for data that must persist between restarts.
+
+## Dockerfile
+
+Add a Dockerfile only when deployment or app-container local dev needs it. If added, copy dependency manifests before source files for cache efficiency.

.agents/skills/fastapi-python-arch/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: fastapi-python-arch
+description: Architecture guide for this Python/FastAPI service.
+---
+
+# FastAPI + Python Architecture
+
+Keep the app boring until requirements force structure.
+
+## Current Shape
+
+- `main.py` owns the FastAPI app.
+- `requirements.txt` pins runtime dependencies.
+- `compose.yml` owns local backing services only.
+
+## When Adding Code
+
+- Keep route handlers thin.
+- Move reusable provider/model/business logic into plain Python modules.
+- Use Pydantic models at trust boundaries.
+- Do not add packages for small stdlib jobs.
+- Add the smallest runnable check for non-trivial logic.

.agents/skills/git-commit/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: git-commit
+description: Split working tree changes into logical commits following this project's convention (`<type> :: <한글 요약>`), auto-detect Git Flow (warn before committing directly to develop/main), and commit without pushing.
+compatibility: Requires git
+---
+
+## Step 1 — Inspect Changes
+
+```bash
+git status --short
+git diff
+git diff --staged
+```
+
+If there are no changes (staged or unstaged), report that and exit.
+
+## Step 2 — Git Flow Check
+
+```bash
+git branch --show-current
+```
+
+If the current branch is `main`, `master`, or `develop`, warn the user before committing directly and ask for confirmation. Prefer committing on a feature/fix branch.
+
+## Step 3 — Group Into Logical Commits
+
+Read the diff and group changed files by concern (one feature, one fix, one config change, etc.). If the working tree mixes unrelated concerns, split into multiple commits using targeted `git add <files>` instead of `git add -A`. Do not bundle unrelated changes into a single commit just for convenience.
+
+## Step 4 — Write Commit Messages
+
+Format (see `AGENTS.md`):
+
+```
+<type> :: <한글 요약>
+```
+
+- `type`: `feat`, `fix`, `refactor`, `chore`, `docs`, `test`, `style`, `perf` 중 하나
+- 요약은 한글로, 무엇을 했는지 간결하게
+
+Example: `feat :: JWT 인증 필터 추가`, `fix :: API 키 조회 NPE 수정`
+
+**어트리뷰션 주의**: 커밋 메시지에 "Co-Authored-By", "Generated by Codex" 같은 트레일러나 서명을 추가하지 않는다. 커밋 작성자는 로컬 `git config user.name`/`user.email`(사용자 본인 계정)을 그대로 따른다 — 별도로 identity를 바꾸지 않는다.
+
+## Step 5 — Commit
+
+```bash
+git add <grouped-files>
+git commit -m "<type> :: <한글 요약>"
+```
+
+여러 그룹이 있으면 그룹마다 반복. **`git push`는 실행하지 않는다** — 푸시는 `write-pr` 스킬 또는 사용자가 직접 수행한다.
+
+## Step 6 — Report
+
+생성된 커밋 목록을 보여준다:
+
+```bash
+git log --oneline -n <생성한 커밋 수>
+```

.agents/skills/migration-guide/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: migration-guide
+description: Migration guide for future DB changes in this Python service.
+---
+
+# Migration Guide
+
+Use only after persistence exists.
+
+## Order
+
+1. Add or update SQLAlchemy models.
+2. Add Alembic migration.
+3. Update service/repository code.
+4. Add or update tests.
+5. Verify upgrade and downgrade when downgrade is supported.
+
+Do not rely on auto-generated migrations without reading the generated SQL.

.agents/skills/planning/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: planning
+argument-hint: [instructions]
+description: Conduct an in-depth structured interview with the user to uncover non-obvious requirements, tradeoffs, and constraints, then produce a detailed implementation spec file.
+---
+
+Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. After I respond to each question, provide your evaluation and recommended answer.
+
+Ask the questions one at a time.
+
+If a question can be answered by exploring the codebase, explore the codebase instead.

.agents/skills/pytest-guide/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: pytest-guide
+description: Pytest and FastAPI TestClient guidance for this repo.
+---
+
+# Pytest Guide
+
+Use pytest only when tests exist or the change needs a real regression check.
+
+## Patterns
+
+- Use plain `assert`.
+- Use FastAPI `TestClient` for endpoint behavior.
+- Keep fixtures local until shared setup is repeated.
+- Mock external provider calls at the module boundary.
+
+## Minimal Example
+
+```python
+from fastapi.testclient import TestClient
+from main import app
+
+
+def test_health():
+    client = TestClient(app)
+    assert client.get("/health").json() == {"status": "ok"}
+```

.agents/skills/resolve-reviews/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: resolve-reviews
+description: Fetch PR review comments, apply valid fixes, and reply with what changed.
+compatibility: Requires git and gh.
+---
+
+# Resolve Reviews
+
+## Steps
+
+1. Resolve current PR with `gh pr view --json number,url`.
+2. Fetch inline comments with `gh api repos/{owner}/{repo}/pulls/{number}/comments`.
+3. Classify each comment as valid, invalid, or needs clarification.
+4. Apply valid fixes only.
+5. Run the smallest relevant checks.
+6. Commit, push, and reply to the review comment with the commit hash.
+
+Do not resolve threads or dismiss comments unless explicitly asked.

.agents/skills/security-checklist/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: security-checklist
+description: Security checklist for Python/FastAPI changes.
+---
+
+# Security Checklist
+
+- No secrets committed outside `.env.example`.
+- No API keys, tokens, or passwords logged.
+- External inputs validated with Pydantic or explicit checks.
+- Provider responses treated as untrusted data.
+- Network calls have clear error handling.
+- CORS/auth changes are reviewed explicitly.
+
+Useful searches:
+
+```bash
+rg -n "password|secret|token|api[_-]?key|sk-" .
+rg -n "print\\(|logger\\..*token|logger\\..*secret" .
+```