From a426218a40d55d54be61b2d3f1f996cd7a8b4136 Mon Sep 17 00:00:00 2001 From: Matthew Mellor Date: Wed, 4 Mar 2026 20:55:05 -0600 Subject: [PATCH] =?UTF-8?q?docs(standards):=20add=20critical=20rule=208=20?= =?UTF-8?q?=E2=80=94=20update=20documentation=20when=20changing=20behavior?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 1 + DEVELOPMENT.md | 6 +++++- content/blog/2026-03-02-introducing-devrail.md | 2 +- content/docs/getting-started/agents.md | 6 +++--- 4 files changed, 10 insertions(+), 5 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 0ee5d72..a5d9f53 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -12,6 +12,7 @@ See DEVELOPMENT.md for the complete reference. 5. **Write idempotent scripts.** Every script must be safe to re-run. Check before acting: `command -v tool || install_tool`, `mkdir -p`, guard file writes with existence checks. 6. **Use the shared logging library.** No raw `echo` for status messages. Use `log_info`, `log_warn`, `log_error`, `log_debug`, and `die` from `lib/log.sh`. 7. **Never suppress failing checks.** When a lint, format, security, or test check fails, fix the underlying issue. Never comment out code, add suppression annotations, disable rules, or mark CI jobs as allowed-to-fail to bypass a failing check. +8. **Update documentation when changing behavior.** When a change affects public interfaces, configuration, CLI usage, or setup steps, update the relevant documentation (README, DEVELOPMENT.md, inline docs) in the same commit or PR. Do not leave documentation out of sync with code. ## Quick Reference diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index dc42cd3..98b0a7c 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -8,7 +8,7 @@ This document is the single canonical source of truth for all DevRail developmen ## Critical Rules -These six rules are non-negotiable. Every developer and every AI agent must follow them without exception. +These eight rules are non-negotiable. Every developer and every AI agent must follow them without exception. 1. **Run `make check` before completing any story or task.** Never mark work done without passing checks. This is the single gate for all linting, formatting, security, and test validation. @@ -22,6 +22,10 @@ These six rules are non-negotiable. Every developer and every AI agent must foll 6. **Use the shared logging library.** No raw `echo` for status messages. Use `log_info`, `log_warn`, `log_error`, `log_debug`, and `die` from `lib/log.sh`. +7. **Never suppress failing checks.** When a lint, format, security, or test check fails, fix the underlying issue. Never comment out code, add suppression annotations (`# noqa`, `# nosec`, `#tfsec:ignore`, `// nolint`), disable rules, or mark CI jobs as allowed-to-fail to bypass a failing check. If a finding is a confirmed false positive, document the justification inline alongside the tool's designated suppression mechanism. + +8. **Update documentation when changing behavior.** When a change affects public interfaces, configuration, CLI usage, or setup steps, update the relevant documentation (README, DEVELOPMENT.md, inline docs) in the same commit or PR. Do not leave documentation out of sync with code. + diff --git a/content/blog/2026-03-02-introducing-devrail.md b/content/blog/2026-03-02-introducing-devrail.md index 840dd47..011cd79 100644 --- a/content/blog/2026-03-02-introducing-devrail.md +++ b/content/blog/2026-03-02-introducing-devrail.md @@ -64,7 +64,7 @@ Universal tools -- trivy, gitleaks, and git-cliff -- run for every project regar ## Agent-Ready by Default -DevRail was built with AI coding agents in mind. The template repositories ship with instruction files for Claude Code (`CLAUDE.md`), Cursor (`.cursorrules`), OpenCode (`.opencode/agents.yaml`), and a generic `AGENTS.md`. Each file inlines six critical rules so agents follow the standard even if they don't read cross-file references. +DevRail was built with AI coding agents in mind. The template repositories ship with instruction files for Claude Code (`CLAUDE.md`), Cursor (`.cursorrules`), OpenCode (`.opencode/agents.yaml`), and a generic `AGENTS.md`. Each file inlines eight critical rules so agents follow the standard even if they don't read cross-file references. The shortest path to agent compliance: diff --git a/content/docs/getting-started/agents.md b/content/docs/getting-started/agents.md index 5502abb..e63882c 100644 --- a/content/docs/getting-started/agents.md +++ b/content/docs/getting-started/agents.md @@ -24,12 +24,12 @@ CLAUDE.md / AGENTS.md / .cursorrules / .opencode/agents.yaml │ ├── Points to DEVELOPMENT.md (full standards reference) │ - └── Inlines 6 critical rules (minimum viable compliance) + └── Inlines 8 critical rules (minimum viable compliance) ``` **Agents that follow cross-file references** (like Claude Code) will read DEVELOPMENT.md and get the complete picture -- language-specific tooling, Makefile contract, shell conventions, everything. -**Agents that ignore cross-file references** still get the six critical rules inlined directly in their instruction file. This ensures minimum compliance regardless of agent capability. +**Agents that ignore cross-file references** still get the eight critical rules inlined directly in their instruction file. This ensures minimum compliance regardless of agent capability. ## Setting Up a Project for Agent Use @@ -94,7 +94,7 @@ If you do not want to commit DevRail files yet, you can paste instructions direc When an agent reads the project's CLAUDE.md (or equivalent), it learns: 1. **DEVELOPMENT.md is the canonical reference.** It contains the full Makefile contract, per-language tooling, shell conventions, and logging standards. -2. **Six critical rules must always be followed.** These are inlined so the agent cannot miss them. +2. **Eight critical rules must always be followed.** These are inlined so the agent cannot miss them. 3. **`make check` is the single gate.** No task is complete until it passes. 4. **Everything runs in Docker.** The agent should never try to install tools on the host.