awesome-vibe-coding-guide

```markdown
# Awesome Vibe Coding Guide: Building a Real-Time Chat Feature with Cursor

## 1. Best Practices for AI-Assisted Coding
- **Prompt Clarity**: Always specify the programming language, framework, and desired outcome. Example: "Write a Python FastAPI endpoint for a real-time chat feature using WebSockets."
- **Modular Design**: Break complex features into smaller functions. Cursor excels at generating isolated components but struggles with end-to-end integration.
- **Validation Checkpoints**: After each AI-generated code block, manually verify:
  - Syntax correctness (use `pyright` for Python)
  - API compatibility (check FastAPI's async requirements)
  - Security considerations (e.g., input sanitization)

## 2. Step-by-Step Implementation
### Step 1: Set Up WebSocket Infrastructure
**Prompt to Cursor**:
"Generate a FastAPI application with WebSocket support for a chat feature. Include:
- Basic FastAPI setup with `/docs` endpoint
- WebSocket endpoint at `/ws/chat`
- Message handling structure
- CORS configuration"

**Expected Output**:
```python
from fastapi import FastAPI, WebSocket
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()
app.add_middleware(CORSMiddleware, allow_origins=["*"])

@app.websocket("/ws/chat")
async def chat_endpoint(websocket: WebSocket):
    await websocket.accept()
    while True:
        data = await websocket.receive_text()
        await websocket.send_text(f"Echo: {data}")
```

**Validation**:
```bash
uvicorn main:app --reload
# Test with: curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" http://localhost:8000/ws/chat
```

### Step 2: Add Message Persistence
**Prompt to Cursor**:
"Extend the FastAPI WebSocket chat to store messages in PostgreSQL using SQLAlchemy. Include:
- Message model with `id`, `content`, `timestamp`, `user_id`
- Database session management
- WebSocket message broadcasting to all connected clients"

**Expected Output**:
```python
from sqlalchemy import create_engine, Column, Integer, String, DateTime
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker

DATABASE_URL = "postgresql://user:password@localhost/db"
engine = create_engine(DATABASE_URL)
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
Base = declarative_base()

class Message(Base):
    __tablename__ = "messages"
    id = Column(Integer, primary_key=True, index=True)
    content = Column(String)
    timestamp = Column(DateTime)
    user_id = Column(Integer)

# Add to chat_endpoint:
@app.websocket("/ws/chat")
async def chat_endpoint(websocket: WebSocket):
    await websocket.accept()
    db = SessionLocal()
    try:
        while True:
            data = await websocket.receive_text()
            message = Message(content=data, timestamp=datetime.now(), user_id=1)
            db.add(message)
            db.commit()
            for connection in active_connections:
                await connection.send_text(f"New message: {data}")
    finally:
        db.close()
```

**Error Handling**: Cursor often misses proper session cleanup. Add:
```python
finally:
    db.close()
```

## 3. Error Handling Strategies
- **Common Pitfalls**:
  - **WebSocket Disconnections**: Implement reconnection logic in frontend (using `reconnecting-websocket` library)
  - **Database Timeouts**: Add `try-except` blocks around DB operations with exponential backoff
  - **API Rate Limiting**: Use FastAPI's `BackgroundTasks` to handle high message volume

## 4. Testing and Debugging
- **Unit Tests**:
  ```python
  def test_websocket_connection():
      with TestClient(app) as client:
          with client.websocket_connect("/ws/chat") as websocket:
              websocket.send_text("test")
              data = websocket.receive_text()
              assert data == "Echo: test"
  ```
- **Load Testing**: Use `locust` to simulate 100+ concurrent users
- **Debugging Tools**:
  - `websocat` for manual WebSocket testing
  - `pgAdmin` for PostgreSQL inspection
  - Cursor's "Explain This Code" feature for complex logic

## 5. Deployment Checklist
- [ ] Configure production PostgreSQL with proper backups
- [ ] Set up FastAPI in production mode (ASGI server like `uvicorn` with `--workers 4`)
- [ ] Implement rate limiting (e.g., `fastapi-limiter`)
- [ ] Add monitoring (Prometheus metrics for message throughput)
- [ ] Set up CI/CD pipeline with GitHub Actions to auto-deploy on `main` branch
```