메뉴
Start the Budget Buddy FastAPI backend server on port 8000 with automatic CORS validation and error detection. Use when starting the backend, fixing server startup issues, debugging connection problems, or when the user asks to run/start the backend.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
Fast headless browser for QA testing and site dogfooding. Navigate pages, interact with elements, verify state, diff before/after, take annotated screenshots, test responsive layouts, forms, uploads, dialogs, and capture bug evidence. Use when asked to open or test a site, verify a deployment, dogfood a user flow, or file a bug with screenshots. (gstack)
Guide React component design for Fogo using the Fogo design system (Industrial Warmth, dark-first, Fogo amber brand color, Tailwind CSS). Use when designing UI, creating components, styling, or writing frontend code.
Review session data model for the v2 two-phase monthly review (Reflect + Plan). Use when building review session CRUD, phase orchestration, conversation entry storage, or the review frontend. Status: BUILT (Phase 3, 2026-04-02).
Model evaluation framework for comparing LLM outputs (Haiku vs Sonnet vs fine-tuned). Use when building eval infrastructure, running model comparisons, or setting up the RLHF training pipeline. Status: PLANNED — build in Phase 2.2.
LLM Gateway interface for all Anthropic API calls in v2. Use when writing any code that calls an LLM, adding new model providers, or understanding how LLM costs are tracked. Status: PLANNED — not yet built.
Configure Buddy AI with Anthropic Claude API and set up automated insight generation via cron jobs (daily, weekly, monthly). Use when setting up Buddy AI, configuring cron jobs, or troubleshooting AI insights.
SOC 직업 분류 기준
| name | backend-server-startup |
| description | Start the Budget Buddy FastAPI backend server on port 8000 with automatic CORS validation and error detection. Use when starting the backend, fixing server startup issues, debugging connection problems, or when the user asks to run/start the backend. |
| allowed-tools | ["Bash(python*)","Bash(pkill:*)","Bash(lsof:*)","Bash(ps:*)","Read","Grep"] |
This skill helps you start the Budget Buddy FastAPI backend server correctly with automatic validation of CORS configuration, API paths, and common startup issues. It prevents the most frequent errors documented in the project's development guide.
.venv//Users/franklindickinson/Projects/budget-buddy-2 (project root)CRITICAL: The backend MUST be started from the project root, not from the /backend directory.
pwd
# Should show: /Users/franklindickinson/Projects/budget-buddy-2
If in wrong directory:
cd /Users/franklindickinson/Projects/budget-buddy-2
lsof -i :8000
If port 8000 is in use, kill the existing process:
pkill -f "uvicorn.*8000"
python -m uvicorn backend.api.main:app --reload --port 8000
Alternative (using server.py entry point):
python backend/server.py
Look for these lines in the output:
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO: Started reloader process
INFO: Started server process
INFO: Application startup complete.
Test with curl:
curl -i http://127.0.0.1:8000/api/v2/transactions
Should return HTTP 200 or data (not 405 or CORS error).
The backend MUST have CORS middleware configured for local development. Check /backend/api/main.py:
from fastapi.middleware.cors import CORSMiddleware
app.add_middleware(
CORSMiddleware,
allow_origins=["http://localhost:3000", "http://127.0.0.1:3000"],
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
Signs CORS is Missing:
405 Method Not Allowed for OPTIONS requestsThe base_path in /backend/api/main.py must be:
base_path = "/api/v2"
Frontend expects: http://127.0.0.1:8000/api/v2/...
When running from project root, Python can find modules with backend. prefix:
from backend.database.session import get_session
from backend.services.database_service import DatabaseService
Cause: Running uvicorn from /backend directory instead of project root
Solution:
cd /Users/franklindickinson/Projects/budget-buddy-2
python -m uvicorn backend.api.main:app --reload --port 8000
Cause: Another process is using port 8000
Solution:
# Find process
lsof -i :8000
# Kill it
pkill -f "uvicorn.*8000"
# Or kill by PID
kill -9 <PID>
Checklist:
base_path = "/api/v2"?http://127.0.0.1:8000/api/v2?Solution:
/backend/api/main.pyBudget Buddy has two backend entry points:
backend/api/main.py (API v2)
base_path = "/api/v2"python -m uvicorn backend.api.main:app --reload --port 8000backend/server.py (Primary)
/apipython backend/server.pyDatabase auto-initializes on startup via startup_event() in server.py:
budget_buddy.db26 routers under /api/v2/:
/transactions - Transaction CRUD/budgets - Budget management/budget-categories - Category definitions/income - Monthly income tracking/ml - Machine learning classification/unified-classification - Combined classification/plaid - Bank integration/accounts - Account management/diagnostics - Health checks/sinking-funds - Sinking fund management/month-end-review - Monthly reflections/weekly-check-in - Weekly reviews/weekly-plans - Weekly planning/merchant-analytics - Merchant insights/buddy - AI insights (Buddy AI)Kill any existing backend process
pkill -f "uvicorn.*8000"
Start backend using this skill's instructions
cd /Users/franklindickinson/Projects/budget-buddy-2
python -m uvicorn backend.api.main:app --reload --port 8000
Verify success
curl http://127.0.0.1:8000/api/v2/transactions
Check CORS
curl -i -X OPTIONS http://127.0.0.1:8000/api/v2/transactions \
-H "Origin: http://localhost:3000" \
-H "Access-Control-Request-Method: GET"
Should return headers including:
access-control-allow-origin: http://localhost:3000
access-control-allow-methods: *
/backend/api/main.py:1-167 - CORS config, base_path, routers/backend/server.py:1-162 - Main server entry point/backend/database/session.py:1-89 - Database initializationCLAUDE.md - Complete development guidelinesrestart_all.sh - Reference startup scriptJanuary 1, 2026