Coding Guidelines & Conventions

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• CONVENTIONS.md
• crates/mcb-domain/src/utils/UTILITIES_POLICY.md
• codex.md
• config/mcb-validate-internal.toml
• crates/mcb-validate/rules/schema.json

Introduction

The Memory Context Browser (MCB) project adheres to a strict set of engineering principles centered around Clean Architecture, deterministic error handling, and automated validation. These guidelines ensure that the codebase remains maintainable, scalable, and robust across multi-agent development environments. The core philosophy emphasizes surgical edits, maximum code reuse, and zero-tolerance for workarounds or suppressed lints.

The project utilizes mcb-validate, a custom architecture rule engine, to enforce layer boundaries and code quality metrics at compile time. This ensures that dependencies flow inward only—from the server and infrastructure layers toward the core domain—preserving the integrity of the business logic.

Sources: AGENTS.md:144-148, codex.md:8-13, CONVENTIONS.md:12-20

Core Architectural Principles

MCB is built on a "Clean Architecture" model where the domain layer sits at the center, free from internal workspace dependencies. This structure is mechanically enforced by mcb-validate using predefined layer boundaries.

Dependency Flow

The following diagram illustrates the unidirectional flow of dependencies within the system:

Layer Definitions

Layer	Responsibility	Allowed Internal Dependencies
mcb-server	MCP protocol, HTTP handlers, and Admin UI	mcb-domain, mcb-infrastructure, mcb-utils
mcb-infrastructure	Wiring, configuration, and composition	mcb-domain, mcb-providers, mcb-utils
mcb-providers	External adapters (Vector stores, embeddings)	mcb-domain, mcb-utils
mcb-domain	Core entities, port traits, and business logic	mcb-utils (leaf)
mcb-utils	Shared agnostic utilities	None

Sources: AGENTS.md:205-216, config/mcb-validate-internal.toml:15-20

Implementation Guidelines

Error Handling

The project mandates deterministic error handling. The use of unwrap(), expect(), or panic! is strictly forbidden in production code paths to prevent runtime crashes.

• Constructors: Use specific domain constructors, e.g., Error::vcs("msg").
• Propagation: Use the ? operator for clean error propagation.
• Banned Patterns: Silent fallbacks (e.g., unwrap_or_default() for critical data) are prohibited. Utilities must fail fast on invalid inputs.

Sources: AGENTS.md:244-246, codex.md:10, crates/mcb-domain/src/utils/UTILITIES_POLICY.md:43-55

Code Style and Metrics

MCB enforces specific code organization rules to prevent "god objects" and maintain readability:

• File Length: Source files should ideally be under ~200 lines (MVI 200). The hard limit enforced by validation is 800 lines.
• Function Complexity: Functions are limited to 50 lines.
• SOLID Limits: Traits are limited to 10 methods; impl blocks are limited to 15 methods to ensure Single Responsibility.
• Lints: unsafe_code and dead_code are denied at the crate level.

Sources: CONVENTIONS.md:21, config/mcb-validate-internal.toml:115-119, config/mcb-validate.toml:44-67

Naming Conventions

Naming must be descriptive and follow specific patterns based on functionality:

• Fallible Operations: Use prefixes like parse_*, try_*, or require_*.
• Validation: Use validate_* for non-mutating checks.
• Mutation: Use canonicalize_* for fallible mutations; avoid normalize_* as it implies infallibility.

Sources: crates/mcb-domain/src/utils/UTILITIES_POLICY.md:32-41

Automated Validation System

The mcb-validate module uses YAML-based rules to scan the codebase for violations. These rules cover categories ranging from architecture to "KISS" (Keep It Simple, Stupid) principles.

Rule Structure

Rules are defined using a specific JSON schema that supports multiple engines, including AST parsing (Tree-sitter) and regex.

Key Validation Thresholds

Rule Type	Metric/Constraint	Limit/Value
SOLID	max_function_params	5
SOLID	max_match_arms	10
Organization	magic_number_allowlist	0, 1, 2, 10, 100, 1000...
Quality	max_file_lines	800 (internal) / 500 (default)
Maintainability	maintainability_index	Minimum 65 (Warning < 50)

Sources: config/mcb-validate.toml:44-77, config/mcb-validate-internal.toml:115-119

Universal Engineering Conduct

For all agents (AI or human), the following "Universal Agent Laws" apply:

1. Fix-Forward-Only: Never revert shared work using git reset or git checkout. Accept the current state and fix issues forward.
2. Root Cause Only: No "temporary" workarounds, TODO comments, or suppression directives (e.g., @ts-ignore, #[allow(dead_code)] without justification).
3. Stay In Scope: Perform exactly the requested task. Do not perform adjacent refactors or cleanups.
4. Evidence-Based Completion: "Done" requires objective evidence, such as command exit codes and output logs.

Sources: AGENTS.md:15-60

Conclusion

Coding at MCB is a disciplined process where architecture is not a suggestion but a compile-time requirement. By adhering to Clean Architecture, strict typing, and automated validation through mcb-validate, the project maintains a high maintainability index and ensures that all contributors—human or AI—operate within a consistent, high-quality framework.
Sources: codex.md, AGENTS.md