# General Code Change

> Converted rule

- Skill: `drmoisan/general-code-change` (Agent Skill)
- Install (CLI): `npx skillmds@latest add drmoisan/general-code-change`
- Raw SKILL.md: https://api.skillmd.com/api/skills/drmoisan/general-code-change/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: drmoisan (https://skillmd.com/u/drmoisan)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/drmoisan/general-code-change

---


# Converted rule

Source: legacy Claude rule `general-code-change`.

# General Code Change Policy

This rule file summarizes the cross-language code change policy for this repository.

## Design Principles

Apply these priorities in order when designing or changing code:

1. **Simplicity first** — Prefer the simplest design that works and is readable. Avoid cleverness and deep indirection.
2. **Reusability** — Factor out logic that is clearly reusable. Avoid copy-paste; share behavior via composition or helper methods.
3. **Extensibility** — Design public APIs so they can be extended without breaking callers. Prefer keyword-style parameters with defaults. Prefer composition over inheritance. Use interfaces/abstract types/protocols to support multiple implementations.
4. **Separation of concerns** — Keep pure logic (transforms, calculations, parsing) separate from I/O (disk, network, DB), UI/CLI, and framework-specific glue.

## Classes, Functions, and APIs

- Create a class when: there is a clear domain concept with data + behavior, state and invariants must travel together, multiple implementations behind an interface are expected, or a multi-step workflow shares context.
- Create a standalone function when: the operation is pure, stateless, and simple; it is a small helper that does not naturally belong on a domain class; or it is a simple transformation from inputs to outputs.
- Keep methods small and focused. Avoid god objects.
- Use interfaces/abstract types/protocols when multiple implementations are likely.

## Module Rigor Tiers

Module rigor tiers (T1–T4) and the uniform-versus-tier-dependent gate matrix are defined in `.agents/skills/quality-tiers.md`. Every project must be classified in `quality-tiers.yml` at repo root.

## Mandatory Toolchain Loop

Run the full seven-stage toolchain in this exact order and repeat until all stages pass in a single pass:

1. **Formatting** (e.g., Black, Prettier, CSharpier, Invoke-Formatter)
2. **Linting** (e.g., Ruff, ESLint, PSScriptAnalyzer, .NET analyzers)
3. **Type checking** (e.g., Pyright, TSC, nullable analysis; skip for PowerShell)
4. **Architecture-boundary tests** (e.g., dependency-cruiser, NetArchTest.Rules)
5. **Unit tests** (e.g., Pytest, Vitest, MSTest, Pester) including property-based tests where applicable per `quality-tiers.md`
6. **Contract / schema compatibility checks** (e.g., oasdiff, schema-snapshot diff)
7. **Integration tests**

**Restart from step 1** if any stage fails or auto-fixes any files. Do not stop the loop until all seven stages complete without errors in a single pass.

Mutation testing and golden tests run in pre-merge or nightly pipelines, not the per-commit loop.

## File Size Limit

- No production code, test code, or reusable script file may exceed **500 lines**.
- Exceptions: temporary throwaway scripts created and deleted within an agent session; raw text fixtures for language-processing test data; Markdown documentation files.

## Error Handling and Logging

- **Fail fast and explicitly**: raise or return clear, specific errors when invariants are violated.
- Do not silently ignore errors. Do not use broad catch-all handlers unless you immediately re-raise or propagate with added context.
- Use the project's established logging pattern. Log at appropriate levels (`debug`, `info`, `warning`, `error`).
- Enforce invariants at construction/initialization time.
- Use assertions only for internal sanity checks, not user-facing error handling.

## Naming

- Names must be descriptive. Abbreviations are acceptable only when they are standard (`id`, `url`, `db`).
- Language-specific conventions: `snake_case` for Python functions/variables, `PascalCase` for Python classes, `camelCase` for TypeScript/C# locals, `PascalCase` for TypeScript/C# types and public members.

## Public APIs and Compatibility

- Prefer keyword-style parameters with defaults.
- Prefer composition over inheritance when possible.
- Avoid breaking public APIs. If a breaking change is necessary, update all callers in-repo and call it out clearly in the change description.

## Dependencies

- Use only libraries already approved in the project unless explicitly told to add more.
- If adding a dependency is unavoidable, choose a well-maintained, widely used package and document why it is required.

## I/O Boundaries

- Isolate I/O (disk, network, APIs) into specific classes or modules.
- Core domain logic must be testable without touching the network or filesystem.
- Use of temporary files within tests is strictly prohibited.