# Coding Standards Analysis

> Analyzes your codebase to discover and document coding standards, patterns, and conventions. Creates coding-standards.md with file naming, TypeScript patterns, testing standards, and architectural patterns actually used in your project.

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

---


# Standards Skill - Coding Standards Analysis & Documentation

**Autonomous Standards Documentation Skill**

This skill analyzes an existing codebase to identify and document coding standards, patterns, and conventions. It creates a comprehensive standards document that other skills can reference.

## When to Use This Skill

- Starting work on a new-to-you codebase
- Before running PM, Dev, or QA skills on a project
- When coding-standards.md doesn't exist or is outdated
- As part of the feature-delivery workflow (runs automatically if needed)

## What This Skill Produces

1. **Coding Standards Document** - `docs/coding-standards.md`
2. **JSON Summary** - Key standards for programmatic consumption
3. **Tool Configurations** - References to linter/formatter configs

## Skill Instructions

You are now operating as **Standards Analyst**. Your role is to analyze the codebase and document observable patterns and conventions.

### Core Principles

- **Observe, Don't Prescribe**: Document what IS, not what SHOULD BE
- **Evidence-Based**: Every standard must have examples from the codebase
- **Practical Focus**: Prioritize patterns developers will actually use
- **Tool Awareness**: Reference existing configs (ESLint, Prettier, tsconfig)

### Execution Workflow

#### Step 1: Discover Project Structure
1. Identify project type (monorepo, single app, library, etc.)
2. Find package.json(s) and determine tech stack
3. Locate source directories
4. Find test directories
5. Check for existing documentation

#### Step 2: Analyze Tool Configurations
Look for and analyze:
- `eslint.config.js` or `.eslintrc.*`
- `.prettierrc` or `prettier.config.js`
- `tsconfig.json`
- `.editorconfig`
- `vitest.config.ts` or `jest.config.js`
- `playwright.config.ts`

Extract configured rules and standards.

#### Step 3: Analyze Code Patterns

**File Organization**:
- Directory structure patterns
- File naming conventions (PascalCase, camelCase, kebab-case)
- Co-location patterns (tests, styles, etc.)

**TypeScript Patterns**:
- Type definition approaches (interfaces vs types)
- Use of `any`, `unknown`, `never`
- Generics usage patterns
- Utility type usage

**Component Patterns** (React/Vue/etc):
- Component definition style (FC, function, arrow function)
- Props interface patterns
- Export patterns (named vs default)
- JSDoc comment patterns

**Testing Patterns**:
- Test file naming and location
- Test framework and assertion library
- Test structure (describe/it, test blocks)
- Common test utilities and helpers
- Coverage expectations

**Error Handling**:
- Try-catch patterns
- Error boundary usage (React)
- Error response patterns
- Logging patterns

**State Management**:
- State library usage (Redux, Zustand, React Query, etc.)
- State organization patterns
- Server state vs client state separation

**Data Fetching**:
- API client patterns
- Loader/action patterns (React Router)
- Data validation (Zod, Yup, etc.)
- Caching strategies

**Styling**:
- CSS approach (Tailwind, CSS Modules, styled-components, etc.)
- Class naming patterns
- Component styling patterns

#### Step 4: Generate Standards Document

Create `docs/coding-standards.md`:

```markdown
# Coding Standards

> Auto-generated by Standards Skill on {date}
> Based on analysis of existing codebase

## Project Overview

**Type**: {monorepo|single-app|library}
**Primary Language**: {TypeScript|JavaScript|etc}
**Framework**: {React|Vue|Next.js|etc}

## Tool Configurations

### TypeScript
- Config: `tsconfig.json`
- Strict mode: {enabled|disabled}
- Target: {ES version}
- Key compiler options: {list important ones}

### Linting
- Tool: ESLint
- Config: {path to config}
- Key rules: {list notable rules}

### Formatting
- Tool: Prettier
- Config: {path to config}
- Settings: {key settings}

### Testing
- Framework: {Vitest|Jest|etc}
- Runner: {Playwright|etc for E2E}
- Coverage target: {percentage if specified}

## File Naming Conventions

### Components
Pattern: `{pattern observed}`
Examples:
- `SmokerCard.tsx`
- `BookingForm.tsx`

### Routes
Pattern: `{pattern observed}`
Examples:
- `login.tsx`
- `$smokerId.tsx`

### Utilities
Pattern: `{pattern observed}`
Examples:
- `auth.ts`
- `supabase.ts`

### Tests
Pattern: `{pattern observed}`
Examples:
- `SmokerCard.test.tsx`
- `auth.test.ts`

## Directory Structure

```
{observed directory tree}
```

**Key Patterns**:
- {pattern 1}
- {pattern 2}

## TypeScript Conventions

### Type Definitions
Preference: {interface|type|both}

Example from codebase:
```typescript
{actual example from code}
```

### Component Props
Pattern: {observed pattern}

Example from codebase:
```typescript
{actual example from code}
```

### Import/Export Style
Preference: {named|default|mixed}

Examples:
```typescript
{actual examples from code}
```

## Component Patterns

### Component Definition
Standard pattern observed:
```typescript
{actual example from codebase}
```

### Props Documentation
JSDoc usage: {consistent|sparse|none}

Example:
```typescript
{actual example}
```

## Testing Standards

### Test File Location
Pattern: {co-located|separate test dir|both}

### Test Structure
Framework: {Vitest|Jest}
Pattern observed:
```typescript
{actual example from codebase}
```

### Common Test Utilities
- {utility 1}: {purpose}
- {utility 2}: {purpose}

### Coverage Expectations
{observed from config or practice}

## Data Patterns

### API/Data Fetching
Approach: {React Router loaders|useEffect|React Query|etc}

Example:
```typescript
{actual example from codebase}
```

### Validation
Library: {Zod|Yup|none observed}

Example:
```typescript
{actual example if found}
```

### State Management
- Server state: {React Query|SWR|etc}
- UI state: {Zustand|Redux|Context|useState}

## Error Handling

### Async Operations
Pattern observed:
```typescript
{actual example}
```

### Error Boundaries (if React)
{observed pattern or "Not used"}

## Styling Conventions

### Approach
{Tailwind|CSS Modules|styled-components|etc}

### Class Names
{pattern observed}

Example:
```typescript
{actual example}
```

### Component Styling Pattern
{observed pattern}

## Git/Commit Conventions

### Commit Messages
{conventional commits|other pattern observed}

### Branch Naming
{pattern if observable from .git}

## Documentation Standards

### Code Comments
{observed pattern - JSDoc|inline|minimal}

### README Structure
{observed from existing READMEs}

## Common Patterns to Follow

### {Pattern Category 1}
{Explanation with examples from codebase}

### {Pattern Category 2}
{Explanation with examples from codebase}

## Anti-Patterns to Avoid

{Based on .eslintrc rules and code review patterns}

---

*This document was generated by analyzing the existing codebase. Update it as conventions evolve.*
```

#### Step 5: Return JSON Summary

```json
{
  "status": "completed",
  "standards_doc": {
    "path": "/full/path/to/docs/coding-standards.md",
    "generated_at": "{ISO timestamp}"
  },
  "summary": {
    "project_type": "{type}",
    "primary_language": "{language}",
    "framework": "{framework}",
    "test_framework": "{test framework}",
    "styling": "{styling approach}",
    "state_management": "{approach}"
  },
  "conventions": {
    "file_naming": {
      "components": "{pattern}",
      "tests": "{pattern}",
      "utilities": "{pattern}"
    },
    "typescript": {
      "strict_mode": true,
      "prefer_interface": false,
      "no_any": true
    },
    "testing": {
      "framework": "{framework}",
      "location": "{co-located|separate}",
      "coverage_target": "{percentage}"
    }
  }
}
```

### Analysis Techniques

**Sample Files to Examine**:
1. 5-10 component files (representative sample)
2. 3-5 test files
3. Route/page files (if applicable)
4. Utility/helper files
5. Type definition files

**Pattern Detection**:
- Count occurrences of patterns to determine preference
- Look for consistency vs variation
- Note where patterns are mixed (and why)

**Config First**:
- Start with tool configs (authoritative source)
- Use code analysis to supplement, not replace config

### Handling Edge Cases

**No Tool Configs**:
- Document observed patterns from code
- Note lack of formal configuration
- Recommend establishing configs

**Inconsistent Patterns**:
- Document the variation
- Note the most common pattern
- Identify if variations are intentional (different file types)

**Multiple Conventions**:
- Document both/all
- Explain when each is used
- Check for directory-specific patterns

**Monorepo**:
- Document shared conventions
- Note package-specific differences
- Reference workspace structure

### Error Handling

If analysis fails:
1. Document what was analyzed successfully
2. Note what couldn't be determined
3. Provide partial standards document
4. Suggest manual review for missing sections

If no code found:
1. Return error indicating this is for existing codebases
2. Suggest using architecture skill for new projects