name	codebase-design
description	Shared vocabulary for designing deep modules, interfaces, seams, and adapters.
metadata	{"author":"mattpocock","version":"1.0.2"}

Codebase Design

Use this when designing or refactoring moodle-mcp-srv modules, especially when deciding where a testable seam belongs.

Module: anything with an interface and implementation. Can be a function, package, CLI command, FastMCP registry, Moodle client, or resource serializer.
Interface: everything a caller must know: signature, invariants, errors, ordering, data shape, configuration, and performance expectations.
Implementation: code behind the interface.
Seam: a place where behavior can vary without editing callers.
Adapter: a concrete implementation that sits at a seam, such as real Moodle HTTP transport or a mock Moodle server.
Depth: leverage exposed through a small interface.
Leverage: more behavior per concept a caller must learn.
Locality: changes, bugs, and tests stay concentrated.

Prefer deep modules: small interface, meaningful behavior behind it.
Use the deletion test: if deleting a module only moves pass-through code, the module is shallow.
The interface is the test surface. Tests should cross the same seam as callers.
One adapter means a hypothetical seam. Two adapters means a real seam.
Do not use "service", "component", "API", or "boundary" when one of the terms above is more precise.

For code changes, run targeted tests first.
Before finishing implementation work, run uv run ruff check, uv run ty check, uv run basedpyright, and relevant pytest commands.

Más de este repositorio

mismo repositorio

Maintain CHANGELOG.md as meaningful merges land. Use after merging a feature branch, before cutting a release, or when asked "what changed?".

Cut a GitHub release by updating changelog, validating release checks, creating a tag, and publishing with gh.

Ship current work through a GitHub pull request using git and gh.

Record durable architectural decisions in docs/adr with compact context and consequences.

Diagnose hard bugs by building a tight repro loop before changing code.

Maintain Moodle MCP domain language and update CONTEXT.md only when terminology is resolved.

name	codebase-design
description	Shared vocabulary for designing deep modules, interfaces, seams, and adapters.
metadata	{"author":"mattpocock","version":"1.0.2"}

Use this when designing or refactoring moodle-mcp-srv modules, especially when deciding where a testable seam belongs.

Module: anything with an interface and implementation. Can be a function, package, CLI command, FastMCP registry, Moodle client, or resource serializer.
Interface: everything a caller must know: signature, invariants, errors, ordering, data shape, configuration, and performance expectations.
Implementation: code behind the interface.
Seam: a place where behavior can vary without editing callers.
Adapter: a concrete implementation that sits at a seam, such as real Moodle HTTP transport or a mock Moodle server.
Depth: leverage exposed through a small interface.
Leverage: more behavior per concept a caller must learn.
Locality: changes, bugs, and tests stay concentrated.

Prefer deep modules: small interface, meaningful behavior behind it.
Use the deletion test: if deleting a module only moves pass-through code, the module is shallow.
The interface is the test surface. Tests should cross the same seam as callers.
One adapter means a hypothetical seam. Two adapters means a real seam.
Do not use "service", "component", "API", or "boundary" when one of the terms above is more precise.

For code changes, run targeted tests first.
Before finishing implementation work, run uv run ruff check, uv run ty check, uv run basedpyright, and relevant pytest commands.