Skip to content

codebase_rules.md

Latest commit

 

History

History
201 lines (153 loc) · 9.43 KB

codebase_rules.md

File metadata and controls

201 lines (153 loc) · 9.43 KB
Raw

Codebase Rules — Root

Summary: This file is the single source of truth for language-neutral coding standards that apply to every package in this repository. It covers repository hygiene, commit conventions, PR policy, testing contracts, secrets handling, documentation requirements, and dependency governance. It contains zero language-specific rules — those live exclusively in each package's own codebase_rules.md. All package-level files must declare ## Inherits pointing here.

Inherits

None. This is the root codebase_rules.md. All other codebase_rules.md files in this repository inherit from this file.

Overrides

N/A — root file, nothing to override.

Language and Runtime

This root file is intentionally language-agnostic. Language version, formatter, linter, and type-checking rules are defined exclusively in package-level codebase_rules.md files. Any rule in this file that references formatting or linting must be understood as a policy contract, not a tooling directive.

Formatting and Style

  • Line length: Maximum 100 characters per line across all languages and file types. Package-level files may override this with a stated justification in their ## Overrides section.
  • Trailing whitespace: Never permitted. CI must reject files with trailing whitespace.
  • Final newline: Every text file must end with a single newline character.
  • Indentation: Defined per language in the package-level codebase_rules.md. Default is 4 spaces for indented languages and 2 spaces for configuration/markup files.
  • Encoding: UTF-8 only. No BOM.

Patterns

Use

  • Immutable data structures and pure functions wherever the language supports them.
  • Explicit return types and function signatures — avoid relying solely on inference for public APIs.
  • Small, single-responsibility functions and modules. A function that does two things should be two functions.
  • Named constants for magic values. A bare 42 or "error" in logic is a defect waiting to happen.
  • Defensive input validation at system boundaries (user input, external APIs, file I/O). Trust internal code; do not defensively re-validate at every internal call site.
  • Structured logging (key=value or JSON). Avoid unstructured print/fmt.Println/console.log debug statements in committed code.

Avoid

  • Global mutable state. If you must use it, document why and scope it to the smallest possible module boundary.
  • Deep nesting (more than 3 levels). Refactor using early returns, guard clauses, or extracted helper functions.
  • Commented-out code blocks. Delete dead code; version control preserves history.
  • TODOs without a linked issue. // TODO: fix this is not acceptable. Use // TODO(#123): ... where #123 is a real open issue.
  • Silent error suppression. Never swallow an error without logging it or returning it to the caller.
  • Re-implementing standard library functionality. Check standard library and approved dependencies first.

Naming Conventions

These are language-neutral defaults. Package-level files must specify language-idiomatic conventions that supersede these where they differ.

Entity Convention Example
Files kebab-case for multi-word filenames user-service.ext
Directories kebab-case data-processing/
Constants UPPER_SNAKE_CASE MAX_RETRY_COUNT
Boolean variables/fields Affirmative predicate form is_enabled, has_permission
Functions that return booleans Affirmative predicate form is_valid(), can_proceed()
Test files Mirror the source file name with a test suffix/prefix language-specific, see package rules

Commit Messages

All commits must follow Conventional Commits format:

<type>(<scope>): <short description>

[optional body]

[optional footer: BREAKING CHANGE: ..., Closes #123]

Allowed types: feat, fix, docs, style, refactor, perf, test, build, ci, chore

Rules:

  • Subject line: imperative mood, lowercase, no trailing period, max 72 characters.
  • Body: wrap at 100 characters. Explain what and why, not how.
  • Breaking changes: must include BREAKING CHANGE: footer and bump the major version.
  • One logical change per commit. Do not bundle unrelated changes.

Pull Requests

  • Size: No PR should touch more than 400 lines of non-generated code. Split larger changes.
  • Scope: Each PR addresses one concern. Mixing features, refactors, and bugfixes in a single PR is not permitted.
  • Tests: Every PR that changes behavior must include or update tests. PRs that only change documentation or comments are exempt.
  • CI must pass before merge. No exceptions. Do not merge with failing CI.
  • Description: Must include a <!-- AGENT TASK --> block (see TASK_HANDOFF.md) or a human-written equivalent covering: what changed, why, and what was tested.
  • Review: At least one human approval required before merge to main / master in supervised and interactive modes. Autonomous mode may merge if all CI checks pass and no escalation flags were raised.

Testing

  • Coverage floor: 80% line coverage minimum for all packages. Packages may raise this floor in their local codebase_rules.md. No package may lower it below 60% without written justification in the ## Overrides section.
  • Test isolation: Tests must not depend on external network resources, real databases, or filesystem state outside a designated temp directory. Mock or stub all external dependencies.
  • Determinism: Tests must produce the same result on every run. Flaky tests must be fixed or quarantined immediately upon detection.
  • Naming: Test names must describe behavior, not implementation. Prefer test_returns_error_when_input_is_empty over test_validate_1.
  • Placement: Language-specific test placement conventions are defined in each package's codebase_rules.md.
  • Agent obligation: Any agent that creates or modifies a function must create or update the corresponding test. This is non-negotiable.

Dependencies

  • Adding a dependency: Requires explicit declaration in the PR description with justification. An agent must escalate if a new dependency introduces a security advisory, changes a public API, or is not from a trusted source.
  • Removing a dependency: Confirm no other package in the repository depends on it before removing. Check the root index.md dependency graph.
  • Pinning: All runtime dependencies must be pinned to exact versions. Development/tooling dependencies may use compatible-version ranges.
  • Banned categories: Cryptographic implementations (use standard library or well-audited packages only), logging frameworks that write to files without rotation, packages with no activity in 24+ months unless no alternative exists.
  • Auditing: Run a dependency security audit as part of CI. Any known vulnerability blocks merge.

Secrets and Security

  • No hardcoded secrets. API keys, passwords, tokens, and private URLs must never appear in source code, configuration files committed to the repository, or log output.
  • Environment variables: Load secrets from environment variables or a secrets manager at runtime. Document required environment variables in the package README.md or index.md.
  • Secret scanning: CI must include a secret-scanning step. A detected secret blocks merge and triggers immediate escalation to a human reviewer.
  • Input sanitization: All data entering from outside the process boundary (user input, HTTP requests, file reads) must be validated and sanitized before use.
  • Agent obligation: If an agent detects a secret pattern (key-like strings, base64 blobs, connection strings with credentials), it must stop, raise an escalation flag, and not proceed until a human has reviewed the finding.

Documentation

  • Public API surface: Every publicly exported function, class, method, and module must have a documentation comment. Language-specific comment syntax is defined in each package's codebase_rules.md.
  • Internal functions: Documentation comments are encouraged but not required for private/ internal functions, unless the logic is non-obvious.
  • Inline comments: Write comments for non-obvious logic, not for obvious code. A comment that merely restates the code in English adds no value.
  • Governance files: index.md, codebase_rules.md, and AGENTS.md must be kept up to date. Outdated governance files are a defect. Agents must flag stale governance files when encountered.
  • Changelog: Significant changes must be captured in commit messages and PR descriptions. Maintaining a separate CHANGELOG.md is optional per package but recommended for published libraries.

File Organization

  • One concern per file. A file that handles HTTP routing should not also contain database logic.
  • Governance files are always at the root of their package directory. Do not nest AGENTS.md, codebase_rules.md, or index.md inside a subdirectory unless that subdirectory is itself a subpackage with its own governance boundary.
  • Generated files: Mark generated files with a header comment (// Code generated by ...). Generated files are exempt from style and line-length rules. Do not manually edit generated files.
  • Temporary files: Never commit .tmp, .bak, or IDE-specific files. These must be listed in .gitignore.