Coding Guidelines

Coding Guidelines is an AI skill that generates, enforces, and maintains coding standards documents tailored to specific teams and technology stacks. It covers style conventions, naming patterns, error handling standards, documentation requirements, and automated enforcement that ensure codebase consistency across contributors.

What Is This?

Overview

Coding Guidelines provides comprehensive coding standard definition and enforcement for software teams. It addresses naming conventions for variables, functions, classes, and files across the codebase, code formatting rules including indentation, line length, and bracket placement, error handling patterns defining how exceptions and errors should be managed, documentation standards specifying when and how to write comments and docstrings, architecture rules governing module dependencies and import patterns, and automated enforcement configuration for linters and formatters.

Who Should Use This

This skill serves team leads establishing coding standards for new teams, architects defining cross-team coding conventions for an organization, developers onboarding to a new team who need to understand its conventions, and teams that want to automate style enforcement to reduce review friction.

Why Use It?

Problems It Solves

Codebases without consistent guidelines become difficult to read and maintain as different developers apply different conventions. Code reviews waste time debating style preferences instead of discussing logic and architecture. New team members struggle to understand implicit conventions that are not documented. Inconsistent error handling and naming patterns create confusion and bugs.

Core Highlights

The skill generates guidelines tailored to the team's programming language and framework. Each rule includes a rationale explaining why it matters, not just what to do. Linter and formatter configurations enforce rules automatically. Example code shows both correct and incorrect patterns for clarity.

How to Use It?

Basic Usage

Coding Guidelines: Python Backend Services

1. Naming Conventions
   - Variables and functions: snake_case
   - Classes: PascalCase
   - Constants: UPPER_SNAKE_CASE
   - Private methods: prefix with single underscore
   - File names: snake_case matching the primary class or module purpose

2. Error Handling
   - Use specific exception types, never bare except clauses
   - Log errors with context before re-raising
   - Define custom exceptions in a module-level exceptions.py file
   - Include the original exception using "from" in exception chains

   Correct:
     try:
         result = await service.process(data)
     except ValidationError as e:
         logger.error("Validation failed for %s: %s", data.id, e)
         raise

   Incorrect:
     try:
         result = await service.process(data)
     except:
         pass

Real-World Examples

pre_commit_config = {
    "repos": [
        {
            "repo": "https://github.com/astral-sh/ruff-pre-commit",
            "rev": "v0.3.0",
            "hooks": [
                {"id": "ruff", "args": ["--fix"]},
                {"id": "ruff-format"}
            ]
        },
        {
            "repo": "https://github.com/pre-commit/mirrors-mypy",
            "rev": "v1.8.0",
            "hooks": [
                {"id": "mypy", "args": ["--strict"]}
            ]
        }
    ]
}

ruff_config = """
line-length = 100
target-version = "py312"

[lint]
select = ["E", "F", "W", "I", "N", "UP", "S", "B", "A", "C4", "PT"]
ignore = ["E501"]  # Line length handled by formatter

[lint.isort]
known-first-party = ["myproject"]
"""

Advanced Tips

Version your coding guidelines document alongside the code so it evolves with the codebase. Create a guidelines decision log explaining why specific conventions were chosen, which prevents recurring debates. Run automated enforcement in CI and make it non-blocking initially to allow gradual adoption.

When to Use It?

Use Cases

Use Coding Guidelines when establishing standards for a new development team, when onboarding developers who need to learn team conventions quickly, when code review discussions frequently devolve into style debates, or when automating code quality checks in CI/CD pipelines.

Related Topics

Code linting tools, code formatters, pre-commit hooks, code review best practices, and developer onboarding documentation all complement coding guideline practices.

Important Notes

Requirements

Agreement among team leads on the conventions to adopt. Linting and formatting tools compatible with the team's programming languages. A documentation location accessible to all team members.

Usage Recommendations

Do: automate as many guidelines as possible through linters and formatters to reduce manual enforcement burden. Include the reasoning behind each guideline so developers understand the purpose rather than blindly following rules. Review and update guidelines periodically as the team and codebase evolve.

Don't: create guidelines so strict that they slow down development without proportional quality benefit. Enforce guidelines retroactively on the entire codebase at once, as this creates massive diffs. Treat guidelines as permanent and unchangeable when the team identifies rules that are counterproductive.

Limitations

Automated tools can enforce formatting and pattern rules but cannot evaluate naming quality or documentation helpfulness. Guidelines work best when the team participates in defining them rather than receiving top-down mandates. Overly detailed guidelines create compliance overhead that reduces development velocity.