LLM Working Guidelines

This document defines mandatory rules for any LLM working on the codebase. These rules are binding and non-negotiable.

Project Scope

Vane is a flow-based network protocol engine written in Rust. It operates across L4, L4+, and L7 using a dynamic, composable pipeline architecture.

Source directory: src/

General Authority

• Maintainers have final decision authority.
• You are responsible for all changes you produce.
• Do not perform actions you believe are incorrect.

Language & Style

• All code, comments, and documentation MUST be written in English.
• Do NOT use subjective language.
• Do NOT add time estimates anywhere.

File Header (Mandatory)

Every source file MUST begin with something like this:

/* src/[relative-path]/[file].rs */

Second line MUST be blank. No exceptions.

Comments

• Use comments only where context or decisions matter.
• Do NOT comment every function.
• Public APIs use ///.
• Implementation details use //.

Code Formatting & Quality

• All code MUST pass the language’s default lint or check tools.
• All code MUST be formatted with the language’s default formatter.
• Compilation failure blocks further work.

Contribution Constraints

• Prefer small, focused changes, breaking is allowed but must be discussed.
• Single source files should not exceed ~1000 lines without justification.
• Follow existing architecture and patterns.

Rust Development Workflow (Mandatory)

After ANY code modification:

1. Run cargo check
2. Fix all errors
3. Report success
4. WAIT for user instruction

Rules:

• NEVER run cargo test without user approval
• NEVER run cargo build unless requested
• ALWAYS run cargo check

Testing Rules

• Write tests ONLY when explicitly requested.
• Allowed: unit-level Rust tests.
• Allowed: integration or end-to-end tests, but DISALLOWED without instruction.

Integration tests are written in Go under integration/tests/.

Hot Reload & Safety

• All config-driven behavior MUST support runtime reload.
• Use atomic update patterns.
• Preserve last-known-good behavior, except update empty file consider as deactivation.

Memory & Performance

• Prefer ownership transfer over cloning.
• Avoid unnecessary allocations.
• Preserve zero-copy paths where possible.

Error Handling

• Use anyhow::Result.
• Add context to errors.
• Do not suppress failures.

Documentation

• Architecture documentation lives in ARCHITECTURE.md.
• Use factual, objective language.
• Do NOT reference /examples.
• Provide complete, independent examples.

Changelog Rules

• Use categories: Breaking, Added, Changed, Fixed (in that order).

Prohibited Actions

• Deviating from file header format
• Mixing languages
• Adding time estimates
• Breaking hot-reload behavior
• Running tests without approval
• Ignoring existing patterns
• Modifying TODO.md without user explicit request

Default Principle

When uncertain: Follow existing code and documentation and offer suggestions which fit best practice and have clear discussions with users