Project Conventions

Project Conventions

This skill guides you in discovering and applying project-specific conventions. Every codebase has its own patterns and practices -- your job is to find them and follow them.

Convention Discovery Process

Step 1: Project Configuration

Check these files for explicit conventions:

Code Style:

• .eslintrc*, eslint.config.* -- JavaScript/TypeScript linting rules
• .prettierrc*, prettier.config.* -- Formatting rules
• pyproject.toml, setup.cfg, .flake8 -- Python config
• .editorconfig -- Editor settings
• ruff.toml, .ruff.toml -- Ruff linter config

Project Structure:

• tsconfig.json -- TypeScript paths and settings
• package.json -- Scripts, dependencies
• pyproject.toml -- Python project config

Documentation:

• CONTRIBUTING.md -- Contribution guidelines
• CLAUDE.md -- AI coding guidelines
• README.md -- Project overview
• docs/ -- Extended documentation

Step 2: Existing Code Patterns

Study the codebase to find implicit conventions:

File Organization:

• List component directories to see how they are organized
• Search for test file patterns (*.test.*, *_test.*, test_*)
• List utility directories (src/utils/, src/lib/, src/helpers/)

Naming Patterns:

• Search file contents for exported function naming patterns
• Search for class naming patterns
• Look for consistent prefix/suffix conventions

Import Patterns:

• Search for import style (absolute vs relative)
• Check if path aliases are configured

Step 3: Similar Features

Find features similar to what you're building:

1. Search for similar functionality:

   • Search for files matching the feature name
   • Search file contents for related terms

2. Study the implementation:

   • How is it structured?
   • What patterns does it use?
   • How does it handle errors?
   • How is it tested?

3. Note the patterns:

   • Component structure
   • State management approach
   • API call patterns
   • Validation approach

Common Convention Areas

Naming Conventions

Discover by example:

• Search for function declaration patterns in the codebase
• Search for variable declaration patterns
• Search for component naming patterns (PascalCase exports)

Common patterns:

• camelCase for functions/variables
• PascalCase for components/classes
• UPPER_SNAKE for constants
• kebab-case for file names (some projects)
• snake_case for file names (Python)

File Structure

Discover the pattern:

• List the contents of example component directories
• List the contents of feature module directories

Common patterns:

Flat structure:

components/
  Button.tsx
  Button.test.tsx
  Button.styles.ts

Folder per component:

components/
  Button/
    index.ts
    Button.tsx
    Button.test.tsx
    Button.module.css

Feature-based:

features/
  auth/
    components/
    hooks/
    api.ts
    types.ts

Error Handling

Discover the pattern:

• Search for try-catch patterns in the codebase
• Search for custom error types extending Error
• Search for error handling in API layers

Apply what you find:

• Use the same error types
• Follow the same handling pattern
• Match logging approach

Testing Patterns

Discover the pattern:

• Read the first 50 lines of existing test files to understand structure
• Read test setup files
• Read test utility files

Match the patterns:

• Test file location (co-located vs separate)
• Naming convention (*.test.ts vs *.spec.ts)
• Setup and teardown approach
• Mocking strategy
• Assertion style

API Patterns

Discover the pattern:

• Search file contents for fetch, axios, or API call patterns
• Search for API response handling patterns

Match the patterns:

• How are endpoints defined?
• How is authentication handled?
• What's the error format?
• How are responses typed?

Convention Application Checklist

When implementing a feature, verify you're following conventions for:

Code Style

• Variable naming matches existing code
• Function naming matches existing code
• File naming follows project pattern
• Import style matches (absolute vs relative)

Structure

• File location follows project structure
• Component organization matches
• Export style matches (default vs named)

Patterns

• Error handling follows project patterns
• Async patterns match existing code
• State management follows project approach
• API calls follow established patterns

Testing

• Test file location is correct
• Test naming follows convention
• Test structure matches existing tests
• Mocking approach is consistent

Documentation

• Comments follow existing style
• JSDoc/docstrings match project
• README updates if needed

When Conventions Conflict

Sometimes you'll find inconsistent patterns:

1. Prefer newer code -- Recent files often reflect current team preferences
2. Prefer maintained code -- Active parts of the codebase reflect current practices
3. Prefer documented conventions -- Explicit rules in configs override implicit patterns
4. Ask if unclear -- When in doubt, ask the user which pattern to follow

Red Flags

Watch for these signs that you might be breaking conventions:

• Your code looks very different from surrounding code
• You're using a library/pattern not used elsewhere
• Your file structure doesn't match siblings
• Your naming feels inconsistent with the codebase
• Linting errors (the project has explicit rules you're breaking)

When you notice these, stop and investigate the existing conventions more carefully.

Integration Notes

What this component does: Provides a systematic process for discovering and applying project-specific conventions. Guides agents through configuration file checks, code pattern analysis, and similar feature study to ensure new code matches existing codebase style.

Capabilities needed:

• File operations (read config files, list directories)
• Search by pattern (find test files, component directories)
• Search by content (find naming patterns, import styles)

Adaptation guidance: This skill is a methodology guide rather than an executable workflow. Agents load it to understand how to discover conventions before implementing features. The discovery steps use generic file operations that work on any platform.

Configurable parameters: None.