# Agentic Coding

This document covers Nova’s conventions for AI-assisted development: how shared project guidance is structured, what belongs in `AGENTS.md`, and how contributors should configure local tooling.

## Philosophy

Nova’s approach to agentic coding is minimal scaffolding and native discovery: if a convention must be followed it is documented in human-readable prose that agents can find via normal file exploration. Agent context files are kept short so they route rather than encode knowledge.

## Principles

### Tool-neutral documentation

Nova contributor documentation is written for contributors first. Mention specific AI coding tools only when documenting tool-specific behavior or local configuration examples. Prefer general wording such as “contributors” and “readers” when the guidance applies to everyone.

### Canonical human-readable docs

Project rules and conventions belong in human-readable documentation, `HACKING.rst`, or deterministic tooling. Avoid adding agent-only project rules. If a rule matters for the project, document it where contributors can find it and let agents discover the same source.

### Deterministic enforcement

Prefer deterministic checks over prose-only instructions. When a convention can be enforced by a hacking check, linter, test fixture, or validation script, use that mechanism instead of relying on a person or an agent to remember prose.

### Minimal routing

Root `AGENTS.md` is a compact routing layer plus high-signal guardrails. It is not a tutorial, not a contributor guide, and not a replacement for the project documentation it links to. Keep it short enough that tools will read it and then follow its pointers to authoritative sources.

## AGENTS.md

`AGENTS.md` at the repository root provides terse routing pointers and a small set of guardrails for common incorrect actions. It should contain only information that is difficult for an agent to discover from source, config, or existing docs, and that is likely to prevent an incorrect action.

Appropriate content includes:

- pointers to authoritative contributor, testing, and subsystem docs;

- guardrails for common incorrect actions not obvious from source or config;

Avoid adding:

- long-form explanations;

- summaries of docs that may drift from the source of truth;

- rules already enforced by `tox -e pep8` or other validation;

- personal preferences or in-progress notes.

When `AGENTS.md` approaches 100 lines, prune existing content before adding more, consolidating into contributor docs as required.

## Local scratch files

Use `.tmp/` for local plans, scratch notes, generated prompts, and other ephemeral output from coding tools. The directory is gitignored and should not appear in upstream review history.

## Local tool configuration

Local override files are tool-specific preferences. There is currently no standard format or name for a project-local override file. Some tools support files such as `CLAUDE.local.md` or `AGENTS.override.md`; others use different names or do not support local instruction files. Configure these locally according to the tool being used.

Do not assume another contributor’s tool will read the same local files or use the same precedence rules. Shared project guidance belongs in the checked-in Nova docs and root `AGENTS.md` routing layer.

Some tools do not natively support `AGENTS.md` and instead look for a tool-specific file at the repository root. For these tools, the recommended approach is a local symlink so that checked-in project guidance remains in `AGENTS.md` without duplicating it.

`CLAUDE.md` is gitignored so contributors can maintain a personal file without it appearing in upstream review history. If a tool expects `CLAUDE.md` at the root, create a local symlink:

    ln -s AGENTS.md CLAUDE.md

## Tool invocation

Assume project tools are installed and available on `$PATH`. Invoke them directly in examples and automation, for example:

    tox -e pep8

Do not install tools system-wide with a package manager or `pip` (`apt install`, `dnf install`, `pip install`, `pip install --user`, and similar). If a required Python tool is not on `$PATH`, `uvx` or `pipx run` are acceptable ephemeral fallbacks. Do not use those wrappers as the primary invocation for project commands.

## Commit messages

See Commit Messages for Nova commit message guidance, including Developer Certificate of Origin sign-off, Gerrit `Change-Id` footers, and AI attribution trailers.

this page last updated: 2026-08-20 01:33:50

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

found an error? report a bug