AGENTS.md · netdata/netdata

Sections

1. Goals
2. Requirement Language
3. Working With The User
4. Development Principles
5. SOW System
6. Durable Artifacts
7. Repository Rules

First lines (shown under the repo's GPL-3.0 license)

# AGENTS.md

## Goals

This repository is the Netdata Agent codebase: a large, multi-language, multi-platform monolith serving production
monitoring, troubleshooting, data collection, alerting, storage, streaming, cloud integration, packaging, and
documentation workflows.

Work here MUST prioritize root-cause understanding, correctness, performance, maintainability, portability,
security, and consistency with existing project conventions.

Critical rules:

1. You MUST find the root cause of a problem before offering a solution. Patching without understanding the
   problem is not allowed.
2. Before patching code, you MUST understand the codebase and the implications of the change: what else is
   affected, what else uses this code.
3. Do not duplicate code. Check whether similar code already exists and reuse it.

## Requirement Language

This repository uses RFC-style requirement language. Durable AI-facing artifacts (instruction files, specs, skills)
SHOULD use these words when documenting enforceable rules:

- **MUST** / **REQUIRED**: mandatory. Violating work is not acceptable unless the user explicitly changes the
  requirement.
- **MUST NOT**: prohibited.
- **SHOULD** / **RECOMMENDED**: expected default. Deviate only with evidence and explain the trade-off.
- **MAY** / **OPTIONAL**: allowed, not required.

## Working With The User

Roles:

- **User**: purpose, scope decisions, design forks, risk acceptance, destructive approvals, final product judgment.
- **Assistant**: investigation, evidence, implementation, tests or equivalent validation, reviews, documentation,
  memory updates, concise reporting. The assistant proposes and investigates; the user approves.

Communication:

- Do your homework before asking questions or requesting decisions. Check every related aspect and possibility so
  questions are informed and to the point.
- Never write walls of text unless asked. Be simple, direct, lean, ordered by importance: give the full picture
  first, start from the high level, let the user ask for details.
- Never agree with the user when the facts contradict their understanding. You MUST always describe the risks and
  implications of their decisions clearly. You are helpful when you reveal the truth accurately, not when you agree.
- Ask the user only for irreducible product, design, or risk decisions.

When a user decision is needed:

1. Present concrete evidence: files and lines, or source references.
2. Provide numbered options.
3. Explain pros, cons, implications, and risks of each.
4. Recommend one option with reasoning.
5. Record the decision in the SOW before implementation. For the goal/plan approval round, the bar is the
   Approval bar (Development Principles, Definitions).

## Development Principles

These principles are mandatory for every task. Code is cheap to add and expensive to live with: a larger diff that
removes debt beats a smaller one that preserves it.

### Definitions

- **Work categories**: defined under "When A SOW Is Required". Trivial changes and read-only work are exempt from
  the implementation record-the-target, disclosure, and reference-search rules below; the clean-end-state preference
  still applies to changes. Read-only work may use local tracking when the user requests it.
- **Approved scope**: the union of (a) the issue or user request, (b) the SOW Purpose and Acceptance Criteria as
  recorded in the SOW, and (c) the migration/contract surface they imply.
- **Coupled item**: code, config, docs, or tests the current change makes redundant or leaves inconsistent (a
  replaced path, its callers, its tests).
- **Independent work**: new work is genuinely independent only if ALL hold: (a) the approved clean end state is
  complete and correct without it, (b) it is not a coupled item or a remaining reference recorded under the target,
  (c) it has its own separable acceptance criteria.
- **User-owned fork**: competing designs, a public-contract change, a destructive or irreversible step, or unclear
  scope.
- **Approval bar** (used by every gate): the user explicitly accepts a trade-off, goal, or plan that you stated in
  your own words (what stays redundant or partial, and why). A bare "ok" or "sounds good" to a one-sided pitch is
  not approval.
- **Mandatory pause**: you MUST present the evidence, STOP, and obtain explicit user approval (Approval bar) before
  proceeding, before requesting non-draft review, and before marking the work complete. It is triggered whenever the
  delivered state would fall short of the recorded target for any reason other than approved staged delivery, and by
  any user-owned fork.
- **Default on doubt**: investigate uncertainty before classifying work. Suspected low-risk coupling follows the
  explicit include-and-disclose rule under "Clean End State Over Less Churn". Ask when a material scope, contract,
  or risk fork remains unresolved. If an intended change's risk remains unclear, treat the change as non-trivial;
  read-only investigation follows "When A SOW Is Required".

### Clean End State Over Less Churn

- You MUST recommend and deliver the clean end state: the structure the codebase SHOULD have once the approved
  scope is fully delivered, including removing the code, config, docs, and tests the change makes redundant. Not
  the smallest diff. You MUST NOT relabel the smallest working diff as "the clean end state".
- Record the target: before generating options, record the clean end state in the SOW. For staged work each stage's
  SOW records its own target, and the stages together MUST reach the full target. Any option that does not match
  the recorded target is a non-clean state and triggers the Mandatory pause.
- Open design decision: when the clean end state is itself the user's design decision, do not invent a fixed
  target. Record a provisional target plus the open question and resolve it with the user first.
- The recorded target MUST account for affected items:
  - (i) removed or migrated: redundant code, config, docs, tests, and their replacement when applicable;
  - (ii) intentionally retained: items and references that remain valid in the delivered state, with their rationale;
  - (iii) deferred or excluded: every coupled item omitted from the delivered state, with its reason, scope source,
    and required user approval and follow-up tracking.
  Excluding an in-scope or coupled item without recording it is silent scope-narrowing and is prohibited. Retention
  under (ii) MUST NOT disguise unfinished migration work; such work belongs under (iii) and the Mandatory pause.
- You are not the scope authority:
  - Coupled cleanup is in scope. You MUST NOT reclassify in-scope or coupled work as "independent" or "out of
    scope" to avoid it, and you MUST NOT silently drop it.
  - When you only suspect coupling and including it is low-risk and confined to what you are changing, include it
    and disclose it rather than stopping to ask.
  - Pause for the user only when inclusion would expand the blast radius, change a user-visible contract, or the
    boundary is itself a genuine scope fork.
- Touch the mess you touch: when code you modify already contains adjacent duplication, dead code, or a clear
  pre-existing defect, you SHOULD clean it as part of this work rather than build on it, provided the cleanup is
  low-risk and confined to the code you are already modifying. Cleanup reaching into unrelated code is independent
  work (see "Scope Discipline At Every Step"). If you leave adjacent mess in place, record why under disclosure (iii).
- Reference search (when replacing a path or altering a contract):
  - You MUST run and record in the SOW (command and result) a search for remaining references to the replaced path
    or contract. Search construction sites and prefixes too, not only literal final names; identifiers here are often
    built dynamically (for example via `fmt.Sprintf`).
  - Every relevant search hit MUST have a disposition under (i), (ii), or (iii), or the target is incomplete.
    Legitimate retained references, such as negative regression tests mentioning a retired identifier, belong under
    (ii). Record and explain unrelated search matches. An item you did not search for counts as silent scope-narrowing.
  - A repository-wide search cannot prove safety for consumers outside this repo (Netdata Cloud, exporters,
    streaming, ML, the docs pipeline). Renaming a shipped public contract is a user-owned breaking decision routed
    through the Mandatory pause, not something the search clears.
- Allowed exceptions (pause conditions, not auto-routes). Recommend a non-clean route ONLY for:
  - (a) technically impossible: impossible to implement correctly at all, NOT within a preferred diff size;
  - (b) a concrete, evidenced safety risk: a named hazard such as data loss or a security/production-stability
    regression, NOT "a larger diff is riskier";
  - (c) confirmed by the user as outside the approved scope;
  - (d) accepted by the user, through the Mandatory pause, as an in-scope partial to ship now.
- Exception evidence: for (a)/(b) you MUST cite specific evidence (file/line, failure class, or test) and route
  through the Mandatory pause; you do not self-certify "unsafe". For (d) track the remainder per Followup Discipline
  with why deferral is acceptable and when it lands; repeatedly shipping partials is debt accumulation, not delivery.
- Never valid: unsupported claims of risk reduction, review convenience, smaller diff, and issue staging do not
  justify a non-clean route and MUST NOT be relabeled "unsafe" or "independent". The evidenced-hazard exception
  above remains available with the required evidence and user approval.
- Re-evaluation checkpoints: at the completion of each planned step, before opening or updating a PR, and before
  marking a SOW completed, you MUST re-evaluate the written changes against the recorded target AND check for drift
  outside the approved scope. You SHOULD also re-evaluate whenever you pause to report progress. Do not keep a
  compromise only because it already exists in the branch.
- Staged delivery (mechanics: "Umbrella And Step SOWs"):
  - Allowed ONLY when every stage is an in-scope decomposition of one approved clean end state and the stages
    together reach it.
  - The approval recorded for the staged plan covers the intermediate states, so an approved stage does not
    re-trigger the pause.
  - Every later stage MUST be tracked per Followup Discipline before an earlier stage merges; "a later stage will
    finish it" with no tracked item is not acceptable.
- Re-ground staged designs: a design recorded during planning or an earlier stage MAY have drifted from the code a
  previous stage produced. Before implementing a later stage you MUST re-verify its design against the current
  code and record the correction in the SOW. Never implement against stale assumptions.
- Deferral check: before recommending deferral, check the issue, SOW, acceptance criteria, and affected migration
  scope. Silence or ambiguity MUST NOT be read as permission to defer. If those sources do not clearly place the
  work outside the target, treat it as in-scope and either complete it or pause for a user decision.

### Plan Before Non-Trivial Work

- Non-trivial work MUST start with a plan recorded in the SOW before any implementation-file change and before any
  implementation-equivalent action: migrations, deletions, pushes, non-draft PRs, external-state mutations via tools.