# Project Conventions

> Guides discovery and application of project-specific conventions including code patterns, naming, structure, and team practices. Use when exploring a codebase or implementing features to match existing patterns.

- Skill: `majiayu000/project-conventions-6` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add majiayu000/project-conventions-6`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/project-conventions-6/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/project-conventions-6

---


# 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.