coder/.claude/docs/WORKFLOWS.md

Development Workflows and Guidelines

Quick Start Checklist for New Features

Before Starting

• Run git pull to ensure you're on latest code
• Check if feature touches database - you'll need migrations
• Check if feature touches audit logs - update enterprise/audit/table.go

Development Server

Starting Development Mode

• Use ./scripts/develop.sh to start Coder in development mode
• This automatically builds and runs with --dev flag and proper access URL
• ⚠️ Do NOT manually run make build && ./coder server --dev - use the script instead

Development Workflow

1. Always start with the development script: ./scripts/develop.sh
2. Make changes to your code
3. The script will automatically rebuild and restart as needed
4. Access the development server at the URL provided by the script

Code Style Guidelines

Go Style

• Follow Effective Go and Go's Code Review Comments
• Create packages when used during implementation
• Validate abstractions against implementations
• Test packages: Use package_test naming (e.g., identityprovider_test) for black-box testing

Error Handling

• Use descriptive error messages
• Wrap errors with context
• Propagate errors appropriately
• Use proper error types
• Pattern: xerrors.Errorf("failed to X: %w", err)

Naming Conventions

• Names MUST tell what code does, not how it's implemented or its history
• Follow Go and TypeScript naming conventions
• When changing code, never document the old behavior or the behavior change
• NEVER use implementation details in names (e.g., "ZodValidator", "MCPWrapper", "JSONParser")
• NEVER use temporal/historical context in names (e.g., "LegacyHandler", "UnifiedTool", "ImprovedInterface", "EnhancedParser")
• NEVER use pattern names unless they add clarity (e.g., prefer "Tool" over "ToolFactory")
• Abbreviate only when obvious

Comments

• Document exported functions, types, and non-obvious logic
• Follow JSDoc format for TypeScript
• Use godoc format for Go code

Database Migration Workflows

Migration Guidelines

1. Create migration files:

   • Location: coderd/database/migrations/
   • Format: {number}_{description}.{up|down}.sql
   • Number must be unique and sequential
   • Always include both up and down migrations

2. Use helper scripts:

   • ./coderd/database/migrations/create_migration.sh "migration name" - Creates new migration files
   • ./coderd/database/migrations/fix_migration_numbers.sh - Renumbers migrations to avoid conflicts
   • ./coderd/database/migrations/create_fixture.sh "fixture name" - Creates test fixtures for migrations

3. Update database queries:

   • MUST DO: Any changes to database - adding queries, modifying queries should be done in the coderd/database/queries/*.sql files
   • MUST DO: Queries are grouped in files relating to context - e.g. prebuilds.sql, users.sql, oauth2.sql
   • After making changes to any coderd/database/queries/*.sql files you must run make gen to generate respective ORM changes

4. Handle nullable fields:

   • Use sql.NullString, sql.NullBool, etc. for optional database fields
   • Set .Valid = true when providing values

5. Audit table updates:

   • If adding fields to auditable types, update enterprise/audit/table.go
   • Add each new field with appropriate action (ActionTrack, ActionIgnore, ActionSecret)
   • Run make gen to verify no audit errors

Database Generation Process

1. Modify SQL files in coderd/database/queries/
2. Run make gen
3. If errors about audit table, update enterprise/audit/table.go
4. Run make gen again
5. Run make lint to catch any remaining issues

API Development Workflow

Adding New API Endpoints

1. Define types in codersdk/ package
2. Add handler in appropriate coderd/ file
3. Register route in coderd/coderd.go
4. Add tests in coderd/*_test.go files
5. Update OpenAPI by running make gen

API Design Guardrails

• Add swagger annotations when introducing new HTTP endpoints. Do this in the same change as the handler so the docs do not get missed before release.
• For user-scoped or resource-scoped routes, prefer path parameters over query parameters when that matches existing route patterns.
• For experimental or unstable API paths, skip public doc generation with // @x-apidocgen {"skip": true} after the @Router annotation. This keeps them out of the published API reference until they stabilize.

Testing Workflows

Test Execution

• Run full test suite: make test
• Run specific test: make test RUN=TestFunctionName
• Run with race detector: make test-race
• Run end-to-end tests: make test-e2e

Test Development

• Use table-driven tests for comprehensive coverage
• Mock external dependencies
• Test both positive and negative cases
• Use testutil.WaitLong for timeouts in tests
• Always use t.Parallel() in tests

Git Workflow

Git Hooks

You MUST install and use the git hooks. NEVER bypass them with --no-verify. Skipping hooks wastes CI cycles and is unacceptable.

The first run will be slow as caches warm up. Consecutive runs are significantly faster (often 10x) thanks to Go build cache, generated file timestamps, and warm node_modules. This is NOT a reason to skip them. Wait for hooks to complete before proceeding, no matter how long they take.

git config core.hooksPath scripts/githooks

Two hooks run automatically:

• pre-commit: Classifies staged files by type and runs either the full make pre-commit or the lightweight make pre-commit-light depending on whether Go, TypeScript, SQL, proto, or Makefile changes are present. Falls back to the full target when CODER_HOOK_RUN_ALL=1 is set. A markdown-only commit takes seconds; a Go change takes several minutes.
• pre-push: Classifies changed files (vs remote branch or merge-base) and runs make pre-push when Go, TypeScript, SQL, proto, or Makefile changes are detected. Skips tests entirely for lightweight changes. Allowlisted in scripts/githooks/pre-push. Runs only for developers who opt in. Falls back to make pre-push when the diff range can't be determined or CODER_HOOK_RUN_ALL=1 is set. Allow at least 15 minutes for a full run.

git commit and git push will appear to hang while hooks run. This is normal. Do not interrupt, retry, or reduce the timeout.

NEVER run git config core.hooksPath to change or disable hooks.

If a hook fails, fix the issue and retry. Do not work around the failure by skipping the hook.

Working on PR branches

When working on an existing PR branch:

git fetch origin
git checkout branch-name
git pull origin branch-name

Then make your changes and push normally. Don't use git push --force unless the user specifically asks for it.

Commit Style

Format: type(scope): message. See CONTRIBUTING.md for full rules. PR titles are linted in CI.

• Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
• Scopes must be a real path (directory or file stem) containing all changed files
• Omit scope if changes span multiple top-level directories
• Keep message titles concise (~70 characters)
• Use imperative, present tense in commit titles

Code Navigation and Investigation

Using LSP Tools (STRONGLY RECOMMENDED)

IMPORTANT: Always use LSP tools for code navigation and understanding. These tools provide accurate, real-time analysis of the codebase and should be your first choice for code investigation.

Go LSP Tools (for backend code)

1. Find function definitions (USE THIS FREQUENTLY):

   • mcp__go-language-server__definition symbolName
   • Example: mcp__go-language-server__definition getOAuth2ProviderAppAuthorize
   • Quickly jump to function implementations across packages

2. Find symbol references (ESSENTIAL FOR UNDERSTANDING IMPACT):

   • mcp__go-language-server__references symbolName
   • Locate all usages of functions, types, or variables
   • Critical for refactoring and understanding data flow

3. Get symbol information:

   • mcp__go-language-server__hover filePath line column
   • Get type information and documentation at specific positions

TypeScript LSP Tools (for frontend code in site/)

1. Find component/function definitions (USE THIS FREQUENTLY):

   • mcp__typescript-language-server__definition symbolName
   • Example: mcp__typescript-language-server__definition LoginPage
   • Quickly navigate to React components, hooks, and utility functions

2. Find symbol references (ESSENTIAL FOR UNDERSTANDING IMPACT):

   • mcp__typescript-language-server__references symbolName
   • Locate all usages of components, types, or functions
   • Critical for refactoring React components and understanding prop usage

3. Get type information:

   • mcp__typescript-language-server__hover filePath line column
   • Get TypeScript type information and JSDoc documentation

4. Rename symbols safely:

   • mcp__typescript-language-server__rename_symbol filePath line column newName
   • Rename components, props, or functions across the entire codebase

5. Check for TypeScript errors:

   • mcp__typescript-language-server__diagnostics filePath
   • Get compilation errors and warnings for a specific file

Investigation Strategy (LSP-First Approach)

Backend Investigation (Go)

1. Start with route registration in coderd/coderd.go to understand API endpoints
2. Use Go LSP definition lookup to trace from route handlers to actual implementations
3. Use Go LSP references to understand how functions are called throughout the codebase
4. Follow the middleware chain using LSP tools to understand request processing flow
5. Check test files for expected behavior and error patterns

Frontend Investigation (TypeScript/React)

1. Start with route definitions in site/src/App.tsx or router configuration
2. Use TypeScript LSP definition to navigate to React components and hooks
3. Use TypeScript LSP references to find all component usages and prop drilling
4. Follow the component hierarchy using LSP tools to understand data flow
5. Check for TypeScript errors with diagnostics before making changes
6. Examine test files (.test.tsx) for component behavior and expected props

Troubleshooting Development Issues

Common Issues

1. Development server won't start - Use ./scripts/develop.sh instead of manual commands
2. Database migration errors - Check migration file format and use helper scripts
3. Audit table errors - Update enterprise/audit/table.go with new fields
4. OAuth2 compliance issues - Ensure RFC-compliant error responses

Debug Commands

• Check linting: make lint
• Generate code: make gen
• Clean build: make clean

Development Environment Setup

Prerequisites

• Go (version specified in go.mod)
• Node.js and pnpm for frontend development
• PostgreSQL for database testing
• Docker for containerized testing

First Time Setup

1. Clone the repository
2. Run ./scripts/develop.sh to start development server
3. Access the development URL provided
4. Create admin user as prompted
5. Begin development