grey-haven-code-style（灰色天堂代码风格）

Grey Haven Code Style Standards

Actual coding standards from Grey Haven Studio production templates.

Follow these exactly when working on Grey Haven codebases. This skill provides navigation to detailed examples, reference configs, and templates.

Supporting Documentation

• EXAMPLES.md - Copy-paste code examples for TypeScript and Python
• REFERENCE.md - Complete config files and detailed rule explanations
• templates/ - Ready-to-use starter files
• checklists/ - Code review checklists

Quick Reference

TypeScript/React (Frontend)

Based on cvi-template - TanStack Start + React 19

Key Settings:

• Line width: 90 characters
• Tab width: 2 spaces
• Quotes: Double quotes
• Semicolons: Required
• Trailing commas: Always
• ESLint: Pragmatic (allows any, unused vars)
• Path alias: ~/ maps to ./src/*

Naming Conventions:

• Variables/Functions: camelCase (getUserData, isAuthenticated)
• Components: PascalCase (UserProfile, AuthProvider)
• Constants: UPPER_SNAKE_CASE (API_BASE_URL, MAX_RETRIES)
• Types/Interfaces: PascalCase (User, AuthConfig)
• Database fields: snake_case (user_id, created_at, tenant_id) ⚠️ CRITICAL

Project Structure:

src/
├── routes/              # File-based routing (TanStack Router)
├── lib/
│   ├── components/      # UI components (grouped by feature)
│   ├── server/          # Server functions and DB schema
│   ├── config/          # Environment validation
│   ├── hooks/           # Custom React hooks (use-* naming)
│   ├── utils/           # Utility functions
│   └── types/           # TypeScript definitions
└── public/              # Static assets

Python/FastAPI (Backend)

Based on cvi-backend-template - FastAPI + SQLModel

Key Settings:

• Line length: 130 characters
• Indent: 4 spaces
• Type hints: Required on all functions
• Auto-fix: Ruff fixes issues automatically

Naming Conventions:

• Functions/Variables: snake_case (get_user_data, is_authenticated)
• Classes: PascalCase (UserRepository, AuthService)
• Constants: UPPER_SNAKE_CASE (API_BASE_URL, MAX_RETRIES)
• Database fields: snake_case (user_id, created_at, tenant_id) ⚠️ CRITICAL
• Boolean fields: Prefix with is_ or has_ (is_active, has_access)

Project Structure:

app/
├── config/              # Application settings
├── db/
│   ├── models/          # SQLModel entities
│   └── repositories/    # Repository pattern (tenant isolation)
├── routers/             # FastAPI endpoints
├── services/            # Business logic
├── schemas/             # Pydantic models (API contracts)
└── utils/               # Utilities

Database Field Convention (CRITICAL)

ALWAYS use snake_case for database column names - this is non-negotiable in Grey Haven projects.

✅ Correct:

// TypeScript - Drizzle schema
export const users = pgTable("users", {
  id: uuid("id").primaryKey(),
  created_at: timestamp("created_at").defaultNow(),
  tenant_id: uuid("tenant_id").notNull(),
  email_address: text("email_address").notNull(),
  is_active: boolean("is_active").default(true),
});

# Python - SQLModel
class User(SQLModel, table=True):
    id: UUID = Field(default_factory=uuid4, primary_key=True)
    created_at: datetime = Field(default_factory=datetime.utcnow)
    tenant_id: UUID = Field(foreign_key="tenants.id", index=True)
    email_address: str = Field(unique=True, index=True)
    is_active: bool = Field(default=True)

❌ Wrong:

// DON'T use camelCase in database schemas
export const users = pgTable("users", {
  id: uuid("id"),
  createdAt: timestamp("createdAt"),      // WRONG!
  tenantId: uuid("tenantId"),             // WRONG!
  emailAddress: text("emailAddress"),     // WRONG!
});

See EXAMPLES.md for complete examples.

Multi-Tenant Architecture

Every database table must include tenant isolation:

• Field name: tenant_id (snake_case in DB) or tenantId (camelCase in TypeScript code)
• Type: UUID foreign key to tenants table
• Index: Always indexed for query performance
• RLS: Use Row Level Security policies for tenant isolation
• Repository pattern: All queries filter by tenant_id

See EXAMPLES.md for implementation patterns.

Virtual Environment (Python Projects)

⚠️ ALWAYS activate virtual environment before running Python commands:

source .venv/bin/activate

Required for:

• Running tests (pytest)
• Running pre-commit hooks
• Using task commands (task test, task format)
• Any Python script execution

When to Apply This Skill

Use this skill when:

• ✅ Writing new TypeScript/React or Python/FastAPI code
• ✅ Reviewing code in pull requests
• ✅ Fixing linting or formatting errors
• ✅ Setting up new projects from templates
• ✅ Configuring Prettier, ESLint, or Ruff
• ✅ Creating database schemas
• ✅ Implementing multi-tenant features
• ✅ User mentions: "code standards", "linting rules", "Grey Haven style", "formatting"

Template References

These standards come from actual Grey Haven production templates:

• Frontend: cvi-template (TanStack Start + React 19 + Drizzle)
• Backend: cvi-backend-template (FastAPI + SQLModel + PostgreSQL)

When in doubt, reference these templates for patterns and configurations.

Critical Reminders

1. Line lengths: TypeScript=90, Python=130 (NOT 80/88)
2. Database fields: ALWAYS snake_case (both TypeScript and Python schemas)
3. any type: ALLOWED in Grey Haven TypeScript (pragmatic approach)
4. Double quotes: TypeScript uses double quotes (singleQuote: false)
5. Type hints: REQUIRED in Python (disallow_untyped_defs: true)
6. Virtual env: MUST activate before Python commands
7. Multi-tenant: Every table has tenant_id/tenantId
8. Path aliases: Use ~/ for TypeScript imports from src/
9. Trailing commas: ALWAYS in TypeScript (trailingComma: "all")
10. Pre-commit hooks: Run before every commit (both projects)

Next Steps

• Need examples? See EXAMPLES.md for copy-paste code
• Need configs? See REFERENCE.md for complete config files
• Need templates? See templates/ for starter files
• Reviewing code? Use checklists/ for systematic reviews