RustyMine/src/backend/AGENTS.md

AI Agent Logging and Error Message Standards

Purpose and Scope

• AI agents may only modify logging, tracing, and error‑message behavior within this backend.
• Agents must not alter business logic, API behavior, database models, security logic, or side‑effects.
• These standards apply to all files under src/backend/ unless a more specific AGENTS.md overrides them.

Tracing and Log Levels

The project uses the tracing crate with levels:

• debug — internal visibility only; stripped in production.
• info — surfaced to operators; meaningful high‑level events.
• warn — recoverable issues; requires clear operator‑action context.
• error — failures preventing intended work; must include actionable context.

Logging Rules

1. Audience and Clarity

• info, warn, and error logs must be understandable without reading code.
• Avoid jargon; use short, direct, operator‑focused language.

2. Structured Context

• Prefer structured fields over message concatenation:
  • debug!(user_id, session_id, "create session started")
• Include identifiers needed to trace the event: IDs, operation names, resource names.
• Never log secrets or sensitive personal data.

3. Level Usage

• debug
  • Use freely: function entry/exit, branches, retries, external calls.
  • Document important variables (sanitized) and execution flow.
• info
  • Startup, shutdown, major lifecycle transitions.
  • Successful user‑facing or operator‑visible actions.
• warn
  • Recoverable anomalies: timeouts, degraded performance, transient failures.
  • Provide remediation hints where appropriate.
• error
  • Non‑recoverable failures or aborted operations.
  • Include outcome, failing subsystem, and relevant identifiers.

4. Error Reporting and Mapping

• Map internal errors to clear user/operator‑facing messages.
• Internal details belong in structured debug logs.
• When propagating errors upward, note:
  • what failed,
  • why it matters,
  • what the impact is.

5. Consistency

• Use imperative mood: "fetch user", "persist record failed".
• Prefer keywords indicating outcome:
  • started, completed, failed, skipped, retrying.
• Never log success at warn or error.

6. Safety and Redaction

• Never log:
  • passwords
  • auth tokens
  • secrets/keys
  • full PII
• Redact or hash where necessary.

7. Placement Requirements

Agents should insert at least:

• Function entry/exit logs (debug).
• Logs before/after:
  • DB operations
  • external HTTP calls
  • filesystem interactions
• Branch decisions:
  • permission checks
  • fallbacks
  • retries/backoff
• All error paths.

8. Formatting

• Prefer single‑line messages under 120 chars.

• Use lowercase, no trailing punctuation.

• Example:

  debug!(user_id, "update permissions started")
  error!(user_id, "update permissions failed")
  

9. Testing and Review

• Ensure logs compile in both debug and release.
• Review for appropriate levels and clarity before merging.

Agent Responsibilities

Agents may:

• Add, remove, or adjust logging/tracing statements.
• Improve error messages and error‑mapping logic.
• Add missing context fields to logs.
• Ensure compliance with this standard.
• Preserve the startup println! banner and metadata in src/backend/src/main.rs for debug visibility.

Agents may not:

• Modify business logic, algorithms, backend behavior, or API responses (other than error messages).
• Change database queries or schemas.
• Add new features, flows, or side‑effects.

Escalation

• Any required change outside logging/error scope must receive explicit human approval before modification.