---
enforcement: high
activation: "paths"
summary: "Check existing and proposed line counts before writing code; warn at 300 lines, split before 500, and extract large additions with descriptive names and purpose comments."
bound_to:
  agents: ["ai-ml-engineer", "blockchain-developer", "build-engineer", "code-reviewer", "component-owner", "data-engineer", "database-optimizer", "debugger", "devops-engineer", "django-expert", "frontend-specialist", "integration-engineer", "kubernetes-expert", "legacy-modernizer", "mobile-developer", "performance-engineer", "react-expert", "reliability-engineer", "self-debug", "software-implementer", "spring-boot-expert", "test-architect", "test-engineer", "toolsmith", "toolsmith-dynamic", "toolsmith-provider"]
  skills: ["address-issues", "agent-loop", "auto-test-execution", "build-poc", "code-chunker", "decompose-file", "flow-delivery-track", "flow-guided-implementation", "flow-iteration-dual-track", "flow-test-strategy-execution", "generate-tests", "ralph", "ralph-external"]
  flows: ["flow-delivery-track", "flow-guided-implementation", "flow-iteration-dual-track", "flow-test-strategy-execution"]
paths: ["**/*.{ts,tsx,js,jsx,mjs,cjs,py,go,rs,java,kt,kts,c,cc,cpp,h,hpp,cs,rb,php,swift,scala,sh,bash,ps1,sql,tf,yaml,yml}"]
triggers:
  - "check file size before generating code"
  - "generated file would exceed 500 lines"
  - "extract additions from oversized code"
---

# Agent Code Generation Guardrails

**Enforcement Level**: HIGH
**Scope**: All code-generating agents (Software Implementer, Test Engineer, DevOps Engineer, etc.)
**Issue**: #405

## Overview

The runtime companion to `agent-friendly-code` (which defines the thresholds: 300-line warning, 500-line error). These rules enforce those thresholds *during* code generation, so agents don't append a 150-line function to a 400-line file and create a 550-line monolith future sessions can't process.

## Mandatory Rules

### Rule 1: Check File Size Before Writing
Before writing to an existing file, estimate current LOC + new LOC. Under 300: write normally. 300–499 (warning zone): write but log a warning. ≥500 (error zone): MUST split — extract the new content to a separate file and import it. Never write a 500+ line file.

### Rule 2: Split New Files Proactively
When creating a new file, don't generate content that exceeds the warning threshold. Split a would-be 450-line multi-method class into focused single-responsibility modules.

### Rule 3: Use Descriptive File Names
Never create generic catch-all names (`utils.ts`, `helpers.ts`, `common.ts`, `misc.ts`, catch-all `types.ts`/`constants.ts`). Name by specific purpose (`src/auth/token-utils.ts`, `src/billing/currency-types.ts`).

### Rule 4: Do Not Enlarge Files Already Over Limits
When modifying a file already over threshold, don't make it worse. Adding >50 lines to an over-warning file: extract the new functionality to a new file, import it (+1 line in the original), and log "File X is at Y lines (over {warning|error} threshold); new functionality extracted to Z."

### Rule 5: Add Module Purpose Statements
Every new file gets a one-line purpose statement at the top (e.g. `// Handles Stripe webhook verification and routing.`).

### Rule 6: Organize Related Files in Directories
When splitting creates 3+ files in one domain, group them in a directory (`src/payment/{card,bank,refund,invoice}.ts`, not `src/payment-card.ts` …).

## Integration

| Rule | Relationship |
|------|-------------|
| agent-friendly-code | defines the thresholds enforced here |
| anti-laziness | don't skip splitting because it's hard |
| executable-feedback | run tests after any split to verify no breakage |
| research-before-decision | research existing structure before deciding where to add code |

## Checklist

Before writing code: checked target file LOC; estimated new content; combined under warning (300) or a split plan ready; combined under error (500) or MUST split; new file names descriptive/greppable; purpose statements added; related files grouped (if 3+); tests run after splitting; warning logged if in the warning zone.

## References

- @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/rules/agent-friendly-code.md — threshold definitions
- @$AIWG_ROOT/agentic/code/addons/aiwg-utils/rules/anti-laziness.md
- @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/rules/executable-feedback.md

---

**Rule Status**: ACTIVE
**Last Updated**: 2026-02-28
