ljwx-children/.claude/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

---

🎯 Project Overview

Gold Template is a production-ready FastAPI microservice template with complete observability, database migrations, and Kubernetes deployment.

Purpose: Rapid microservice development on existing K8s infrastructure (OrbStack)

Key Features:

• 🚀 FastAPI + SQLAlchemy 2.0 (async)
• 📊 Full Observability (Prometheus + Loki + Tempo + Grafana)
• 🗄️ Database Migrations (Alembic with Expand/Contract pattern)
• ☸️ Kubernetes Deployment (Helm + Argo CD GitOps)
• 🤖 Claude Code Integration (4 custom skills)

Tech Stack:

• Backend: Python 3.11+, FastAPI 0.109, SQLAlchemy 2.0, Alembic 1.13
• Database: SQLite (dev), PostgreSQL (prod, shared infra namespace)
• API Design: OpenSpec 0.17.2 (OpenAPI-first workflow)
• Observability: Prometheus, Loki, Tempo, OpenTelemetry, Grafana
• Deployment: Docker, Kubernetes (OrbStack), Helm, Argo CD
• Testing: pytest, pytest-asyncio, pytest-cov

---

📍 Current Project State

Status: Sprint 1 - Claude Development Tools Optimization

Completed (100%):

• ✅ Alembic database migration framework (#26)
• ✅ OpenTelemetry distributed tracing (#27)
• ✅ Grafana observability dashboard (#28)
• ✅ Blueprint v2.0 compliance (23/23 checks)

Current Sprint (In Progress):

• 🚧 Issue #7: Optimize Claude Configuration
• 🚧 Issue #6: Create Prompts Library
• 🚧 Issue #5: Create Code Templates Library

Next Sprint:

• 📋 Issue #8: Auto Task Creation System
• 📋 Issue #9: Auto Progress Update System

Infrastructure Ready:

• ✅ OrbStack K8s cluster (27 namespaces)
• ✅ Postgres, Redis, MySQL (infra namespace)
• ✅ Prometheus, Grafana (monitoring namespace)
• ✅ Loki, Promtail (logging namespace)
• ✅ Tempo, OpenTelemetry Collector (tracing namespace)
• ✅ Argo CD (argocd namespace)

---

⚠️ CRITICAL: Never Do This

Database:

• ❌ NEVER modify published Alembic migrations (create new ones instead)
• ❌ NEVER use SQLite in production (must use PostgreSQL)
• ❌ NEVER do DROP COLUMN in production without Expand/Contract pattern
• ❌ NEVER create non-idempotent migrations (must support re-runs)

Security:

• ❌ NEVER commit .env files, secrets, or credentials to Git
• ❌ NEVER hardcode passwords, API keys, tokens in code
• ❌ NEVER log sensitive data (passwords, tokens, PII, credit cards)
• ❌ NEVER use SQL string concatenation (use ORM parameters)

Deployment:

• ❌ NEVER kubectl apply directly to production (use GitOps/Argo CD)
• ❌ NEVER skip PreSync hooks (database migrations must run first)
• ❌ NEVER deploy without running tests and security scans
• ❌ NEVER force push to main branch

Observability:

• ❌ NEVER use high-cardinality Prometheus labels (user_id, email, etc.)
• ❌ NEVER skip trace_id in logs (breaks log-trace correlation)

---

🚀 Essential Commands

Development (Daily Use)

# Start development server
uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000

# Run tests
pytest tests/ -v                                  # All tests
pytest tests/unit/ -v                             # Unit tests only
pytest tests/ --cov=backend --cov-report=html     # With coverage
pytest --lf                                       # Re-run last failed
pytest -k "test_specific_function"                # Run specific test

# Code quality
black backend/ tests/                             # Format
flake8 backend/ tests/                            # Lint
mypy backend/                                     # Type check
bandit -r backend/                                # Security scan

Database (Alembic)

# Create migration
alembic revision --autogenerate -m "description"

# Apply migrations
alembic upgrade head                              # Apply all
alembic upgrade +1                                # Apply one

# Check status
alembic current                                   # Current version
alembic history                                   # Migration history

# Rollback
alembic downgrade -1                              # Rollback one
alembic downgrade <revision>                      # Rollback to specific

Kubernetes (OrbStack)

# Deploy to OrbStack
./scripts/deploy-orbstack.sh                      # Local (SQLite)
./scripts/deploy-orbstack.sh --mode infra-db      # Use infra Postgres

# Check status
kubectl get all -n gold-template                  # All resources
kubectl get pods -n gold-template                 # Pods only
kubectl describe pod -n gold-template <pod>       # Pod details
kubectl logs -n gold-template -f <pod>            # Follow logs

# Port forwarding
kubectl port-forward -n gold-template svc/gold-template 8000:8000
kubectl port-forward -n monitoring svc/grafana 3000:80
kubectl port-forward -n tracing svc/tempo 16686:16686

# Troubleshooting
kubectl get events -n gold-template --sort-by='.lastTimestamp'
./scripts/monitor.sh logs                         # View logs
./scripts/monitor.sh health                       # Health check

Observability

# Access Grafana
kubectl port-forward -n monitoring svc/kube-prometheus-stack-grafana 3000:80
# Password: kubectl get secret -n monitoring kube-prometheus-stack-grafana -o jsonpath="{.data.admin-password}" | base64 --decode

# Check metrics
curl http://localhost:8000/metrics

# View Tempo traces
kubectl port-forward -n tracing svc/tempo 16686:16686
# Open http://localhost:16686

OpenSpec (API-First Development)

# Validate OpenAPI spec
npm run spec:validate

# Lint OpenAPI spec (Spectral)
npm run spec:lint

# Generate OpenAPI spec from FastAPI
npm run spec:generate

# Sync spec (generate + validate)
npm run spec:sync

# Compare spec changes (detect breaking changes)
npm run spec:diff

# Watch mode (auto-generate on file changes)
npm run spec:watch

Claude Code Skills

# Code review (security + quality + types)
python3 .claude/skills/code-review/review.py

# Generate tests
python3 .claude/skills/test-generator/generate.py --target backend/

# Refactoring suggestions
python3 .claude/skills/refactor-assistant/assistant.py

# Generate OpenAPI spec (alternative)
python3 .claude/skills/api-designer/design.py --format yaml

# Kubernetes helper
python3 .claude/skills/k8s-helper/helper.py --action health -n gold-template

---

🏗️ Architecture (High-Level)

Project Structure

gold-template/
├── backend/                 # FastAPI application
│   ├── main.py             # Entry point (with OpenTelemetry, Prometheus)
│   ├── models/             # SQLAlchemy models
│   └── api/                # API endpoints (to be added)
├── alembic/                # Database migrations
│   ├── versions/           # Migration scripts
│   └── env.py              # Alembic config (async support)
├── deployment/             # Kubernetes deployment
│   ├── helm/               # Helm charts
│   │   └── gold-template/
│   │       ├── templates/  # K8s manifests
│   │       ├── values-orbstack.yaml      # Local dev
│   │       └── values-infra-db.yaml      # Production
│   └── argocd/             # Argo CD Application definitions
├── tests/                  # Test suite
│   ├── unit/               # Unit tests
│   ├── integration/        # Integration tests
│   └── e2e/                # End-to-end tests
├── .claude/                # Claude Code configuration
│   ├── CLAUDE.md           # This file
│   └── skills/             # Custom skills (code-review, test-generator, etc.)
├── docs/                   # Documentation
│   ├── database/           # Database guides
│   └── deployment/         # Deployment guides
└── scripts/                # Automation scripts

Key Files

File	Purpose	When to Modify
backend/main.py:186	FastAPI app, OpenTelemetry, Prometheus	Add endpoints, middleware
backend/models/*.py	SQLAlchemy models	Add/modify database tables
alembic/versions/*.py	Database migrations	Schema changes
requirements.txt	Python dependencies	Add libraries
deployment/helm/gold-template/values-*.yaml	Deployment config	Environment changes
PROMPT_BLUEPRINT_V2.md	Development guidelines	Reference (700+ lines)

Observability Flow

FastAPI App (backend/main.py)
    ↓
┌───────────────┬──────────────┬─────────────┐
│   Metrics     │     Logs     │   Traces    │
│  /metrics     │   stdout     │    OTLP     │
└───────┬───────┴──────┬───────┴──────┬──────┘
        ↓              ↓              ↓
   Prometheus      Promtail    OTel Collector
        ↓              ↓              ↓
   (monitoring)     Loki          Tempo
        ↓          (logging)    (tracing)
        ↓              ↓              ↓
        └──────────→ Grafana ←───────┘
                  (Dashboard)

Database Strategy

Environment	Database	Connection	Config File
Local Dev	SQLite	./gold-template.db	values-orbstack.yaml
Production	PostgreSQL	postgres-infra-postgresql.infra.svc:5432	values-infra-db.yaml

Migration Pattern (Production):

1. Expand: Add nullable column (backward compatible)
2. Backfill: Populate data (optional)
3. Contract: Add NOT NULL constraint (requires all apps upgraded)

---

🤖 Working with Claude Code

Development Workflow (OpenSpec-First, 9 Steps)

1. Design API Spec      → Define endpoint in openapi.yaml (API-first!)
2. Validate Spec        → npm run spec:validate
3. Describe Requirement → Clear, specific request with spec reference
4. Claude Explores      → Reads existing code, understands patterns
5. Claude Implements    → Code matching OpenAPI spec + migrations + tests
6. Claude Adds Observability → Metrics + logs + traces
7. Sync & Validate      → npm run spec:sync (auto-validates)
8. Claude Tests         → Run tests, verify coverage
9. Claude Documents     → Update docs (OpenAPI is always current)

Key Principle: OpenAPI spec is the source of truth. Code must match spec.

Best Practices for Prompting Claude

✅ Good Prompts (Clear & Specific):

"添加用户认证功能：
- 支持 JWT token (7天有效期)
- 用户可以注册、登录、登出
- 密码使用 bcrypt 加密
- 需要 Alembic 迁移脚本（Expand 模式）
- 需要单元测试和集成测试
- 集成 Prometheus metrics（登录成功/失败计数）
- 参考 backend/main.py 的现有模式"

"backend/main.py:145 的 root endpoint 在高并发下出现 JSON 序列化错误。
请分析原因并修复：
1. 可能是 datetime 序列化问题
2. 需要自定义 JSON encoder
3. 添加并发测试验证修复
4. 更新 API 文档"

❌ Bad Prompts (Vague):

"加个登录功能"
"优化性能"
"修复 bug"

Iterative Development (Use Context)

# Round 1: Explore
"分析 backend/models/ 的数据库模型设计，特别是关系定义"

# Round 2: Design (builds on Round 1)
"基于现有模型，设计一个订单管理模块（Order, OrderItem）"

# Round 3: Implement (builds on Round 2)
"实现订单创建 API，保持与现有代码风格一致"

# Round 4: Test
"为订单模块生成全面的测试用例"

# Round 5: Review
"运行 code-review skill 检查安全问题"

Claude Must Deliver (Checklist)

For any feature, Claude's output must include:

• OpenAPI Spec: Update openapi.yaml FIRST (design before code!)
• Code: FastAPI endpoints + Pydantic models matching spec + business logic
• Database: Alembic migration (if schema changes)
• Tests: At least unit tests (aim for >80% coverage) + spec validation
• Observability: Prometheus metrics + structured logs + trace spans
• Spec Validation: Run npm run spec:sync to ensure code matches spec
• Deployment: Helm values update (if env vars/secrets needed)
• Documentation: OpenAPI spec is the docs (always up-to-date)

---

📚 Real-World Examples

Example 1: Adding a New Feature

User Request:

"添加商品管理功能：
- 商品模型：name, price, description, stock, category
- API: 创建、查询、更新、删除商品
- 支持分页查询
- 需要完整的可观测性"

Claude Process:

1. Explore:

   Uses Task tool (Explore agent) to analyze:
   - Existing SQLAlchemy models (backend/models/)
   - API endpoint patterns (backend/main.py)
   - Test structure (tests/)
   

2. Design:

   Proposes:
   - Product model (SQLAlchemy with async)
   - Alembic migration (create_products_table.py)
   - API endpoints (POST /products, GET /products, etc.)
   - Pydantic schemas (ProductCreate, ProductUpdate, ProductResponse)
   - Metrics: product_operations_total{operation="create|update|delete"}
   

3. Implement:

   • Creates backend/models/product.py
   • Creates alembic/versions/20250101_001_create_products.py
   • Adds endpoints to backend/main.py or backend/api/products.py
   • Adds Prometheus metrics and trace spans
   • Creates tests/test_products.py

4. Verify:

   alembic upgrade head
   pytest tests/test_products.py -v --cov=backend
   uvicorn backend.main:app --reload
   curl -X POST http://localhost:8000/products -d '{"name":"Test","price":99.99}'
   

Example 2: Debugging a Production Issue

User Request:

"生产环境出现 500 错误，日志显示 Database connection failed。
trace_id: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
请帮我分析和修复。"

Claude Process:

1. Analyze Logs (Grafana Loki):

   {namespace="gold-template"} | json | trace_id="a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
   

2. Check Traces (Tempo):

   • Finds trace in Grafana → Tempo
   • Identifies slow database query span (5s timeout)

3. Investigate Configuration:

   • Reads deployment/helm/gold-template/values-infra-db.yaml
   • Checks DATABASE_URL, connection pool settings

4. Propose Fix:

   Issues found:
   1. Missing connection pool configuration
   2. No retry logic for transient failures
   
   Proposed fixes:
   - Add SQLAlchemy pool_pre_ping=True
   - Increase pool_size and max_overflow
   - Add exponential backoff retry decorator
   

5. Implement & Test:

   • Updates database connection in backend/models/__init__.py
   • Adds retry logic
   • Creates integration test for connection failures
   • Deploys via GitOps (update Helm values → Git push → Argo CD syncs)

Example 3: Database Migration (Expand/Contract)

User Request:

"为 users 表添加 email 字段（必填，唯一索引），
使用 Expand/Contract 模式确保零停机部署。"

Claude Delivers 3 Migrations:

Migration 1: Expand (Add Nullable Column)

# alembic/versions/20250101_001_add_email_expand.py
def upgrade():
    op.add_column('users', sa.Column('email', sa.String(255), nullable=True))

def downgrade():
    op.drop_column('users', 'email')

Migration 2: Backfill (Optional)

# alembic/versions/20250101_002_backfill_email.py
def upgrade():
    op.execute("""
        UPDATE users
        SET email = username || '@example.com'
        WHERE email IS NULL
    """)

Migration 3: Contract (Add Constraints)

# alembic/versions/20250101_003_email_constraints.py
def upgrade():
    op.alter_column('users', 'email', nullable=False)
    op.create_index('ix_users_email', 'users', ['email'], unique=True)

Deployment:

# Deploy Migration 1 → Wait for all pods to restart → Deploy Migration 2 → Deploy Migration 3
# Argo CD PreSync hook runs migrations automatically

---

🔍 Quick FAQ

Q: How do I start development?

./scripts/setup.sh              # First time only
source venv/bin/activate
alembic upgrade head
uvicorn backend.main:app --reload
open http://localhost:8000/docs

Q: Alembic migration failed, what do I do?

alembic downgrade -1            # Rollback
# Fix migration script
alembic upgrade head            # Retry

→ Full guide: docs/database/migration-guide.md

Q: How do I see logs in Grafana?

kubectl port-forward -n monitoring svc/grafana 3000:80
# Open http://localhost:3000
# Search: {namespace="gold-template"} | json

→ Password: See "Essential Commands" section

Q: OpenTelemetry trace_id showing as 0?

# Check environment variable
echo $OTEL_ENABLED  # Should be "true"

# Test locally
curl http://localhost:8000/
# Check logs for trace_id (should be 32-char hex)

→ Code reference: backend/main.py:49-50, backend/main.py:62-63

Q: How do I deploy to Kubernetes?

# Local development (SQLite)
./scripts/deploy-orbstack.sh

# Use shared PostgreSQL (infra namespace)
./scripts/deploy-orbstack.sh --mode infra-db

# Check deployment
kubectl get pods -n gold-template
kubectl logs -n gold-template -f <pod-name>

→ Full guide: DEPLOYMENT-GUIDE.md

Q: How do I add a new API endpoint?

1. Read existing patterns: backend/main.py
2. Create endpoint function with FastAPI decorators
3. Add Pydantic request/response models
4. Add Prometheus metrics (REQUEST_COUNT, REQUEST_DURATION)
5. Add trace spans for external calls
6. Create tests
7. Verify at /docs (Swagger UI)

Q: How do I use Claude Code skills?

# Example: Review code before committing
python3 .claude/skills/code-review/review.py

# Or ask Claude directly:
"运行 code-review skill 检查 backend/ 的安全问题"

Q: Where are the detailed guides?

• OpenSpec workflow: docs/workflows/openspec-development-workflow.md ⭐ NEW
• Blueprint (development guide): PROMPT_BLUEPRINT_V2.md (700+ lines)
• Database migrations: docs/database/migration-guide.md (365 lines)
• Implementation plan: IMPLEMENTATION-PLAN.md (23 issues)
• Observability setup: Check completed Issue #27, #28
• Deployment: deployment/helm/gold-template/README.md

---

📖 Key References

Essential Documentation

Document	Purpose	Length
PROMPT_BLUEPRINT_V2.md	Complete development blueprint	700+ lines
IMPLEMENTATION-PLAN.md	23 open issues roadmap	450 lines
docs/database/migration-guide.md	Alembic Expand/Contract guide	365 lines
README.md	Project overview & quickstart	Overview
QUICK-REFERENCE.md	Command cheatsheet	Quick lookup

Code Entry Points

File	Description	Key Functions
backend/main.py:186	FastAPI app initialization	app, configure_opentelemetry()
backend/main.py:138	Root endpoint example	Shows tracing + logging
backend/main.py:181	Metrics endpoint	Prometheus /metrics
alembic/env.py	Alembic async config	Database migration runner
deployment/helm/gold-template/templates/deployment.yaml	K8s deployment	Container spec

Infrastructure Endpoints

Service	Namespace	Access
PostgreSQL	infra	postgres-infra-postgresql.infra.svc:5432
Redis	infra	redis-infra-master.infra.svc:6379
Prometheus	monitoring	prometheus-kube-prometheus-prometheus.monitoring.svc:9090
Grafana	monitoring	Port-forward to :3000
Loki	logging	loki.logging.svc:3100
Tempo	tracing	Port-forward to :16686
Argo CD	argocd	Port-forward to :8080

---

🎓 Learning Path for New Developers

Day 1: Setup & Exploration

1. ./scripts/setup.sh
2. Read README.md and this file (CLAUDE.md)
3. Start app: uvicorn backend.main:app --reload
4. Explore Swagger UI: http://localhost:8000/docs
5. Ask Claude: "分析项目结构，解释主要组件"

Day 2: Development Basics

1. Read PROMPT_BLUEPRINT_V2.md (sections 1-5)
2. Create simple endpoint with Claude's help
3. Run tests: pytest tests/ -v
4. Deploy locally: ./scripts/deploy-orbstack.sh

Day 3: Database & Migrations

1. Read docs/database/migration-guide.md
2. Create Alembic migration: alembic revision -m "test"
3. Apply: alembic upgrade head
4. Rollback: alembic downgrade -1

Day 4: Observability

1. Access Grafana: kubectl port-forward -n monitoring svc/grafana 3000:80
2. View metrics: curl http://localhost:8000/metrics
3. Check logs: {namespace="gold-template"} | json
4. Find traces by trace_id in Tempo

Day 5: Production Deployment

1. Understand GitOps workflow (PROMPT_BLUEPRINT_V2.md section 8)
2. Deploy with infra DB: ./scripts/deploy-orbstack.sh --mode infra-db
3. Monitor: ./scripts/monitor.sh logs
4. Practice rollback: alembic downgrade -1

---

🔄 Development Patterns

Adding a Database Model

# 1. Create model: backend/models/product.py
from sqlalchemy import Column, Integer, String, Float
from .base import Base

class Product(Base):
    __tablename__ = "products"

    id = Column(Integer, primary_key=True)
    name = Column(String(100), nullable=False)
    price = Column(Float, nullable=False)

# 2. Create migration
alembic revision --autogenerate -m "add products table"

# 3. Review and apply
alembic upgrade head

# 4. Create tests
# tests/test_products.py

Adding an API Endpoint

# backend/main.py or backend/api/products.py
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from opentelemetry import trace

class ProductCreate(BaseModel):
    name: str
    price: float

@app.post("/products", response_model=ProductResponse, status_code=201)
async def create_product(product: ProductCreate):
    """Create a new product."""
    tracer = trace.get_tracer(__name__)

    with tracer.start_as_current_span("create_product") as span:
        span.set_attribute("product.name", product.name)

        # Increment Prometheus metric
        PRODUCT_OPERATIONS.labels(operation="create").inc()

        # Business logic
        logger.info("Creating product", extra={"product_name": product.name})

        return {"id": 1, "name": product.name, "price": product.price}

Adding Observability

# Prometheus Metrics
from prometheus_client import Counter

PRODUCT_OPERATIONS = Counter(
    'product_operations_total',
    'Product operations',
    ['operation']  # labels: create, update, delete
)

# Structured Logging
logger.info("Product created", extra={
    "product_id": product.id,
    "user_id": user.id,
    "action": "create"
})

# OpenTelemetry Tracing
tracer = trace.get_tracer(__name__)
with tracer.start_as_current_span("expensive_operation") as span:
    span.set_attribute("key", "value")
    # ... operation ...

---

🛠️ Troubleshooting

Common Issues

Problem: ModuleNotFoundError: No module named 'fastapi'

source venv/bin/activate
pip install -r requirements.txt

Problem: alembic.util.exc.CommandError: Can't locate revision identified by 'abc123'

alembic history        # Check available revisions
alembic stamp head     # Force set to latest (USE WITH CAUTION)

Problem: Pod in CrashLoopBackOff

kubectl describe pod -n gold-template <pod-name>
kubectl logs -n gold-template <pod-name>
# Common causes: DB connection failed, missing env vars, migration failed

Problem: Metrics not showing in Prometheus

# Check ServiceMonitor exists
kubectl get servicemonitor -n gold-template

# Check /metrics endpoint works
kubectl port-forward -n gold-template svc/gold-template 8000:8000
curl http://localhost:8000/metrics

Problem: Traces not appearing in Tempo

# Check OTEL_ENABLED env var
kubectl get deployment -n gold-template gold-template -o yaml | grep OTEL_ENABLED

# Check OpenTelemetry Collector is running
kubectl get pods -n tracing | grep otel-collector

# Test locally
curl http://localhost:8000/
# Check logs for trace_id (should NOT be all zeros)

---

📞 Getting Help

Ask Claude Code:

"我遇到了 <specific issue>，请帮我分析和解决"
"解释 <file_path> 的实现原理"
"为什么 <functionality> 不工作？"

Use Project Skills:

python3 .claude/skills/code-review/review.py        # Security review
python3 .claude/skills/test-generator/generate.py   # Generate tests
python3 .claude/skills/refactor-assistant/assistant.py  # Code quality

Read Documentation:

• Blueprint: PROMPT_BLUEPRINT_V2.md
• Migration guide: docs/database/migration-guide.md
• Implementation plan: IMPLEMENTATION-PLAN.md

Check Issues:

gh issue list                    # Open issues
gh issue view <number>           # View specific issue

---

Current Version: 2.0 (Streamlined) Last Updated: 2025-12-31 Maintained By: DevOps Team

Development Principles:

• 🎯 Simplicity over complexity
• 🤖 Claude Code-first development
• 📊 Observability by default
• 🧪 Test-driven development
• 🚀 GitOps deployment
• 📝 Documentation-driven design

---

Ready to start developing? Ask Claude: "我想添加 ，请帮我设计和实现" 🚀