# Coding Standards

> Project coding standards and conventions. Preload into agents that write code. Use when this capability is needed.

- Skill: `tomevault-io/coding-standards-31` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/coding-standards-31`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/coding-standards-31/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/coding-standards-31

---


# Coding Standards

## Backend Python

### Exception Chaining (REQUIRED)
```python
try:
    result = operation()
except ValueError as e:
    raise ValidationError(str(e)) from e  # ALWAYS chain
else:
    return result
```

### Typed Dependencies (REQUIRED)
```python
from backend.api.deps import SessionDep
from backend.auth.deps import CurrentUser
from backend.rbac.deps import OrgContextDep, TeamContextDep
```

### Domain Exceptions (REQUIRED)
```python
# Use these, not HTTPException or ValueError
raise ResourceNotFoundError("Team", team_id)
raise ValidationError("email", "Invalid format")
raise AuthorizationError("Cannot delete")
```

### Timestamps (REQUIRED)
```python
from datetime import UTC, datetime
now = datetime.now(UTC)  # ALWAYS use UTC
```

### Constants (REQUIRED)
```python
MAX_RETRIES = 3  # Use constants, not magic numbers
```

## Frontend TypeScript

### i18n (REQUIRED)
```typescript
const { t } = useTranslation()
<Button>{t("com_save")}</Button>  // NEVER hardcode strings
```

### Path Aliases (REQUIRED)
```typescript
import { Button } from "@/components/ui/button"  // Use @/ prefix
```

### Error Display (REQUIRED)
```typescript
{mutation.isError && <ErrorAlert error={mutation.error} />}
```

### Form State (REQUIRED)
```typescript
form.setValue("field", value, { shouldDirty: true })
```

### Test IDs (REQUIRED)
```typescript
import { testId } from "@/lib/test-id"

// ALL interactive elements MUST have test IDs
<Button {...testId("feature-submit-button")} onClick={handleSubmit}>{t("com_save")}</Button>
<Input {...testId("feature-name-input")} {...form.register("name")} />
<DialogContent {...testId("confirm-delete-dialog")}>...</DialogContent>
```

**Naming Convention**: `{component}-{element}-{type}` in kebab-case
- Buttons: `create-team-submit-button`, `delete-prompt-confirm-button`
- Inputs: `login-email-input`, `settings-name-input`
- Dialogs: `edit-prompt-dialog`, `delete-org-alert-dialog`
- Lists: `document-list`, `document-item-${id}`
- Tables: `configured-models-table`, `model-row-${id}`

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/davidgaribay-dev) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-14 -->