Agentic coding standards (cross-cutting)

Purpose

This guide defines prescriptive coding and review standards for teams using AI-assisted implementation (IDE assistants, codegen tools, review bots) alongside humans. It applies with any lifecycle or methodology (Scrum, Kanban, phased, etc.). Teams running Forge SDLC use the same rules and map them to Charge, Ember Log, Versona sessions, and Assay evidence as described in the Forge overlay below.

Companion: principles and risks — Agentic SDLC (cross-cutting). Specs and durable intent: Spec-driven development.

---

Scope and layering

Forge teams additionally align sessions and logs with Versona framework — kinds, interfaces, processes, sessions (session layout, §5 structured output when used).

---

Intent and repository as source of truth

1. No chat-only specifications — acceptance criteria, IDs, and constraints live in tracked artifacts (issues, specs, docs/, SDD inputs) that a reviewer can open without scrolling a thread.
2. Link work to intent — commits or PR descriptions reference backlog / requirement / Spark IDs where your process expects traceability (Agentic SDLC (cross-cutting) engineering-tracking table).
3. Prefer spec-first for large AI edits — for non-trivial scope, written intent leads implementation (Spec-driven development); reduces rework and silent scope creep.

---

Generation discipline

1. Minimal, scoped diffs — change only what the work unit requires; avoid drive-by refactors, formatting sweeps, or unrelated file churn.
2. Match house style — naming, structure, and patterns consistent with the surrounding module and team directives (e.g. .cursor/rules/, CONTRIBUTING.md).
3. Split when review would suffer — if agent throughput exceeds review capacity, smaller PRs and lower WIP beat huge batches (Agentic SDLC (cross-cutting) risks).
4. Recoverable steps — prefer commits that are easy to bisect or revert; avoid squashing unrelated concerns into one change.

---

Code analyzability and file footprint

Large files are not a defect by themselves, but source files should usually fit in one focused human or LLM review pass. Tokens matter most for LLM context; LoC and bytes are fast proxies. Treat the table below as advisory, not hard gates.

Default workspace target: tight — sized for local review on a ~4 GB GPU class setup (e.g. Qwen Coder 7B with limited context after model weights). Repos may override via AGENTS.md, .cursor/rules/code-footprint.mdc, or FORGE_CODE_FOOTPRINT_PROFILE.

Rough tokens ≈ file_bytes / 4 (code is often denser than prose). Measure the real model context when possible.

Scanner profiles (code_footprint_scan.py --profile):

Exclude generated or vendor output from footprint analysis: generated website/, showcase/, dist/, build/, minified CDN/vendor assets, generated tutorial HTML/CSS/JS, lockfiles, snapshots, vendored dependencies, and other files where source-of-truth edits happen elsewhere.

Allowed exceptions include parsers, schema catalogs, generated checked-in sources, legacy files being migrated, framework entrypoints with clear local structure, and cohesive files where splitting would increase coupling or hide invariants. Record the reason near the work item, PR, ADR, AGENTS.md, or repo-local standards registry when the exception affects ongoing maintenance.

When splitting a large script, prefer a meaningful folder hierarchy over a flat pile of helpers. Typical partitions are: CLI entrypoint, configuration loading, domain services, IO/adapters, rendering/reporting, tests, fixtures, and shared types. Add a short README.md or INDEX.md in any new folder to explain what belongs there, the entrypoints, and how the files relate.

---

Attribution and identity

1. PR transparency — state AI-assisted work when applicable (tool name optional unless policy requires it); summarize what the human verified.
2. Bot and service accounts — if automation opens PRs or commits, policy should define labels, CODEOWNERS, and how they appear in history (Agentic SDLC (cross-cutting) Contributor row).
3. Audit trail — reviewers must be able to see what changed and why without private chat context.

---

Verification

1. CI and local gates — agreed checks (build, lint, tests) pass before merge unless a recorded, time-bounded exception exists (same bar as non-AI work; see Software development lifecycle Verify phase).
2. Tests are not optional by default — new behavior needs tests or an explicit, reviewed justification in the work record.
3. High-risk areas — auth, crypto, PII, payments, concurrency, and security-sensitive paths require human review and often extra discipline passes (e.g. Security Versona, threat-informed checklist); AI review does not replace that.
4. Regulated contexts — follow organizational sign-off and evidence rules; automation supplements, not replaces, compliance gates.

---

Security

1. LLM application risks — use OWASP Top 10 for LLM as a baseline when models touch prompts, tools, data, or generated code.
2. Secure SDLC overlay — depth for secure design, review, and testing lives under Security / Cybersecurity and related practice guides.
3. Secrets — never commit keys, tokens, or production data into prompts, repos, or recipe configs; use secret stores and ephemeral review environments.

---

AI-assisted code review flow (summary)

1. Bound the change — diff or PR scope, SDLC phase, and risk class.
2. Automated first — linters, tests, SAST/SCA as applicable.
3. Structured discipline pass — optional §5-shaped reviews via Engineering-family Versonas (e.g. Software Engineering, Security, Testing) — see forge/versona/catalog/discipline/engineering/versona-se.mdc.template and Versona contract.
4. Human decision — merge, request changes, or escalate; record material trade-offs in Ember Log or ADRs when Forge or your process requires it.

IDE: teams may install the blueprint Cursor skill from run-engineering-ai-code-review/SKILL.md on GitHub. CI / container: optional template recipe Template recipe: `llm-diff-review` (copy to agents/recipes/ per Orchestration — new agent / recipe).

---

Forge overlay (optional)

Use this mapping when Forge SDLC is the team’s methodology (Forge — deep-dive package (blueprint)).

---

Local visibility (forge-lenses)

The forge-lenses workspace dashboard (python3 -m lenses, default http://127.0.0.1:8080) shows Standards and agentic hygiene on the Overview and each Project page: a heuristic 0–100 score, per-check table, and Suggestions from repository signals (CI, CONTRIBUTING/docs, sdlc/ or blueprints/, .cursor rules or skills, Forge-related paths, lockfiles, optional commit-message sampling). The same structure is returned on each workspace child as standards_compliance in GET /api/workspace-state. This is not a compliance audit — see the forge-lenses dashboard reference and standards_compliance.py for check ids and registry overrides.

---

Related blueprint guides

• Agentic SDLC (cross-cutting) — agentic principles, ceremonies, risks.
• Spec-driven development — durable specs for agentic workflows.
• Forge SDLC — Forge methodology hub.
• Respecting resources — review bottleneck ↔ resource respect; bounded execution posture.
• Autonomy levels — autonomy ladder and human gates per level.
• Roles, archetypes & methodology titles — accountability and Contributor identity.
• Agents blueprint — structure & layers — containerized recipes and optional LLM steps.

Related pages

• Methodology guides (blueprint)
• External reference URLs (methodology guides)
• Agentic SDLC (cross-cutting)
• Agile (umbrella)
• BDD (Behavior-Driven Development)