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 for exported function declarations to find naming conventions
• Search for class declarations to find class naming patterns

Import Patterns:

• Search for import statements to determine style (absolute vs relative)

Step 3: Similar Features

Find features similar to what you're building:

1. Search for similar functionality:

   • Search for files and content related to the feature you are implementing

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 declarations in source files
• Search for variable declarations in source files
• Search for component declarations (capitalized function names)

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 component directories to see the organization style
• List feature module directories to see how features are grouped

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 source files
• Search for custom error types that extend Error
• Search for error handling in API modules

Apply what you find:

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

Testing Patterns

Discover the pattern:

• Read the beginning of existing test files to understand structure
• Read test setup and 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 for API call patterns (fetch, axios, api client usage)
• Read 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 methodology for discovering and applying project-specific conventions -- from configuration files and existing code patterns to testing approaches and API styles. Capabilities needed: File reading, file searching (by name pattern and content) for convention discovery Adaptation guidance: This is a methodology guide, not a tool-specific workflow. The discovery steps describe what to look for; adapt the specific search operations to your platform's file access capabilities.