Hardening Codebases for Agentic Engineering

Schedule

The time frames are only estimates and may vary according to how the class is progressing.

Section 1 Presentation: Why Codebase Hardening Matters for Agentic (30 minutes)

This section frames the problem: Agentic engineering coding produces uneven outcomes because agents amplify the engineering system around them. A hardened codebase gives agents fast, executable feedback. A weak codebase gives them ambiguity, and too many unsafe degrees of freedom.

Topics covered:

• The bimodal reality of agentic engineering outcomes: some teams see faster, safer delivery; others see more churn, defects, review burden, and production risk.
• AI as an amplifier of existing engineering practice.
• Why “more code faster” is not the same as better software delivery.
• Recipes vs. taste concept: prompts, README files, coding standards, and Markdown specs are recipes; tests, invariants, static checks, architecture rules, observability, and review judgment provide taste.
• Tests as just-in-time prompting: failing tests tell an agent what “correct” means at the moment it needs feedback.
• Runtime assertions and invariant checks as just-in-time debugging signals.
• Why hardened codebases matter across typed and dynamically typed ecosystems.
• What “agent-ready” means in practice:
• executable acceptance criteria
• meaningful tests
• runtime invariants
• architecture boundaries
• fast local quality gates
• useful debugging surfaces
• human review focused on judgment rather than mechanical checking
• Learner engagement:
• Short Q&A.

Section 2 Demonstration: Hardening a Weak Codebase (50 minutes)

The instructor demonstrates hardening a small, intentionally weak codebase before asking an AI agent or developer to safely extend it. The goal is to show the actual mechanics of making a repository push back against unsafe changes.

Starting state of the demo codebase:

• unclear input and output contracts
• thin or overly happy-path tests
• missing edge-case coverage
• no runtime invariants
• unclear architecture boundaries
• brittle mocks or fake confidence
• weak error messages
• limited local quality checks
• Demonstrated hardening steps:
• Convert vague behavior into executable acceptance tests.
• Add runtime invariant checks with actionable failure messages.
• Add edge-case coverage using table-driven, property-based, or fuzz-style tests.
• Add or tighten static quality checks using language-appropriate tooling.
• Add an architecture boundary check that prevents a forbidden dependency or layering violation.
• Replace a brittle mock with a contract test or realistic fake implementation.
• Improve error output, logs, CLI behavior, or dry-run feedback so failures are easier to understand.
• Show how each guardrail provides feedback to future human or AI changes.
• Key teaching point:
• The best prompt is often not more text in the chat. It is a failing executable check inside the repo.
• Learner engagement:
• Learners predict which guardrail will catch which failure.
• Short Q&A.
• Break (10 minutes)

Section 3 Hands-On Exercise: Add Guardrails to a Codebase (60 minutes)

Learners work on a starter codebase that is intentionally under-hardened. Their task is to add concrete guardrails that make the repository safer for future human and agentic engineering changes.

Exercise goal:

Before an AI agent works in this repository, make the repository capable of rejecting unsafe changes.

Learners complete several of the following:

• Add one executable acceptance test for important behavior.
• Add one runtime invariant, assertion, validator, or contract check.
• Add one edge-case test using table-driven, property-based, fuzz-style, or scenario-based testing.
• Add or tighten one static quality gate, such as a compiler setting, linter rule, formatter, type check, security scan, or dependency check.
• Add one architecture boundary check.
• Improve one error message, log line, health check, CLI command, dry-run mode, or debug output.
• Replace one brittle test pattern with a more realistic contract test or fake implementation.
• Learner engagement:
• Pair or small-group work.
• End-of-exercise share-out.
• Q&A focused on implementation tradeoffs.

Section 4 Presentation: Advanced Patterns and Adoption Strategy (30 minutes)

This section closes with higher-leverage hardening techniques and practical guidance for adopting them without turning the codebase into tool soup.

Topics covered:

• Mutation testing: checking whether tests actually detect behavioral changes.
• Deterministic simulation and replayable failures.
• State-space thinking with tools such as TLA+.
• Formal methods and theorem proving for high-risk logic.
• Contract tests for services, APIs, and integration boundaries.
• Reducing over-mocking with dependency injection and realistic fakes.
• Practical adoption sequence:
• start with tests around risky behavior
• add invariants where state can be corrupted
• add architecture rules where coupling hurts
• add fast local checks before expensive CI checks
• improve failure messages so humans and agents can act on them

What to avoid:

• relying only on prompts or Markdown instructions
• adding slow gates that nobody runs locally
• writing tests that assert implementation details instead of behavior
• allowing AI agents to skip tests
• confusing generated code volume with engineering progress

Closing:

• Agentic engineering works best when the codebase has taste. The goal is not to write longer prompts. The goal is to build feedback systems that can tell plausible code from good code.
• Learner engagement:
• Final Q&A.
• Learners identify one hardening technique they can apply immediately in their own codebase.