Agentic Guardrails

Reusable workflow templates that keep AI coding agents from shipping sloppy code.

These are markdown-based instructions that any AI coding agent can follow — Cursor, Claude Code, opencode, Aider, Gemini CLI, or anything else that reads markdown.

The Problem

AI coding agents are remarkably productive. They're also remarkably consistent at generating specific categories of bad code:

• Unnecessary comments — # increment counter above counter += 1
• Defensive over-engineering — try/except blocks catching exceptions that can't be raised
• Gratuitous abstraction — AbstractFooFactory with one concrete implementation
• Phantom error handling — catching TypeError, ValueError, KeyError when only KeyError is possible
• Docstring regurgitation — restating the function name and parameter types without adding insight
• Over-parameterization — do_logging=True, validate=True, use_cache=True flag soup
• Type assertion hacks — cast(Any, ...) and # type: ignore to paper over type issues
• Dead code — commented-out blocks, unused imports, unreachable branches
• Duplicate functions — re-inventing helpers that already exist in the codebase, session after session
• Inconsistent style — new code that doesn't match the patterns of the surrounding file

These aren't bugs. They pass tests. They pass linters. But they accumulate into a codebase that's harder to read, harder to maintain, and increasingly full of noise. Every session with an AI agent leaves a little residue.

Agentic Guardrails is a set of four workflow files that catch these problems before they hit your commit history.

The Workflows

Four markdown files, designed to be run in sequence. Each focuses on exactly one concern.

Workflow	Focus	Key Action
01-hardening	Code quality	Fix spaghetti, extract constants, improve naming
02-consolidation	Deduplication	Find functions that already exist elsewhere
03-slop	AI code cleanup	Detect and remove the patterns listed above
04-commit	Quality gate + commit	Lint, typecheck, test, then commit properly

Design Principles

• Single focus per workflow. An agent looking for spaghetti code should NOT also be hunting for duplicates. Mixed concerns produce worse results.
• Checkpoint before mutation. Each workflow presents its findings and waits for your approval before changing code. You stay in control.
• Test after every fix. Any workflow that changes code runs the project's test suite afterward to confirm nothing broke.
• Generic from the start. No hardcoded tool names. Every workflow discovers the project's commands from AGENTS.md — works with any language, any toolchain.

The Chain

01 Hardening ──→ 02 Consolidation ──→ 03 Slop ──→ 04 Commit
     │                  │                 │              │
  checkpoint         checkpoint       checkpoint    quality gate
  (approve fixes)   (approve merges)  (approve removals) (lint/test/commit)

Each workflow ends with a nudge toward the next one. You decide whether to continue, skip, or stop.

The Slop Checklist

Even if you don't adopt the full workflow chain, this checklist is worth keeping. Run it against any AI-generated code change:

🔍 What to look for in AI-generated diffs

Unnecessary comments

• Comments restating what the code does
• Comment density that doesn't match the rest of the file
• Docstrings that restate function names and parameter types verbatim

Defensive over-engineering

• try/except catching exceptions the called code doesn't raise
• None checks not needed given the function's contract and callers
• Overly broad except Exception where a specific type is appropriate

Type assertion hacks

• cast(Any, ...) to silence errors instead of fixing them
• # type: ignore without justification
• Unnecessary isinstance checks papering over type issues

Gratuitous abstraction

• Base classes, interfaces, or factories for a single implementation
• Wrapper functions that forward arguments without adding logic
• *args, **kwargs when the function always receives the same specific arguments

Inconsistent style

• Naming conventions that don't match the surrounding file
• Different quote styles, import ordering, or formatting
• Error handling patterns that diverge from the codebase

Dead code

• Commented-out code blocks
• Unused imports
• Unreachable branches

Leftover debugging

• print(), breakpoint(), console.log() from debugging
• Unresolved TODO/FIXME/HACK comments added in this change

Over-parameterization

• Boolean flags that should be separate functions
• Functions with 5+ parameters that should accept a config object

Getting Started

1. Copy the workflows

# Clone and copy just the workflow files
git clone https://github.com/YOUR_USERNAME/agentic-guardrails.git
cp -r agentic-guardrails/workflows/ your-project/.agent/workflows/

Or just download the four files from workflows/ and put them wherever your agent expects workflow instructions.

2. Have an AGENTS.md

The workflows discover your project's commands by reading AGENTS.md (or your equivalent). At minimum, it should document:

## Build/Lint/Test Commands

### Linting & Formatting
npm run lint        # or: ruff check . --fix
npm run format      # or: ruff format .

### Type Checking
npx tsc --noEmit    # or: mypy .

### Testing
npm test            # or: pytest

See examples/ for a complete example.

3. Run the chain

Invoke each workflow manually with your agent of choice:

Cursor: Reference the file in your prompt — "Follow the instructions in .agent/workflows/finalize-01-hardening.md"

Claude Code: /read .agent/workflows/finalize-01-hardening.md then "Execute this workflow"

opencode: Use the /workflow command or reference the file directly

Aider: Paste the workflow content or reference it as context

Any agent: The workflows are plain markdown instructions. Any agent that can read files and run terminal commands can follow them.

Workflow Details

01 — Code Hardening

Reviews each changed file for:

• Hardcoded values — magic numbers/strings that should be constants
• Abstraction placement — logic in the wrong module, functions doing too much
• Spaghetti indicators — circular deps, mixed concerns, reaching into module internals
• Maintainability — naming, consistency, error handling patterns
• Breaking changes — altered function signatures, changed return types
• Test coverage gaps — flags missing tests (does NOT write them)

Presents findings at a checkpoint, then fixes only what you approve.

02 — Consolidation

Finds functions that were written but already exist elsewhere:

• Searches by similar names (verb + noun matching)
• Searches by key operations (grep for shared logic patterns)
• Searches by parameter signatures and return types

Organizes findings into three tiers: exact duplicates, near-duplicates, and look-alikes. You decide which to merge.

03 — Slop Removal

Scans the diff for the AI-generated code patterns listed in the slop checklist above, plus:

• Secret scanning — API keys, tokens, private keys, connection strings
• Over-parameterization — boolean flag soup, too many parameters

Presents findings, waits for your approval, removes what you agree with.

04 — Quality Gate & Commit

Runs all mechanical checks discovered from AGENTS.md:

1. Lint and format
2. Type check (if configured)
3. Full test suite
4. Fix-and-rerun loop (max 3 cycles)

Then stages files properly (individually, never git add .), drafts a commit message matching the repo's style, and commits. Only pushes if you explicitly ask.

FAQ

Do I need all four workflows? No. Each stands alone. Use 03-slop by itself if you just want AI code cleanup. Use 04-commit by itself if you just want a disciplined commit process. They're better together, but not required together.

What if my project doesn't have an AGENTS.md? The workflows will still work — they'll just skip the discovery step and rely on standard project conventions. But you'll get better results with one. It takes 5 minutes to write.

Does this work with languages other than Python? Yes. The workflows are language-agnostic. They discover commands from your AGENTS.md, so they work with TypeScript, Rust, Go, Java, or anything else. The slop patterns are universal.

Can I customize the workflows? Absolutely. They're markdown files. Add items to the slop checklist, remove categories that don't apply, adjust the staging deny-list — make them yours.

Why not automate the chain into one command? The checkpoints are the point. Each workflow pauses for your judgment — "is this try/except actually unnecessary?" "should these functions really be merged?" Automating that away removes the value. You're the human in the loop.

Contributing

Found a slop pattern that's missing? Have a workflow improvement? PRs welcome. The bar for new slop checklist items is: "Does this happen consistently across multiple AI agents and codebases?"

License

MIT — use it, fork it, adapt it. See LICENSE for details.