AI Engineering: Agents and Applications › AI Coding Agents › Day 303

Hands-on lab — Day 303: Working with a Coding Agent

Commands

Setup

pip install -r requirements/requirements.txt

Run

python examples/spec_compiler.py

Test

bash tests/run_tests.sh

File tree

examples/spec_compiler.py
expected-output/examples-run.txt
expected-output/FIELDS.md
expected-output/measured-values.txt
expected-output/run-output.txt
expected-output/starter-run.txt
expected-output/test-output.txt
expected-output/test-run.txt
metadata.yml
README.md
requirements/requirements.txt
security.md
starter/spec_compiler.py
tests/run_tests.sh
tests/test_spec_compiler.py
troubleshooting.md

Lab README

Day 303 Lab: Working with a Coding Agent

Lesson

Purpose

Build a Specification Compiler and Context Bundler in Python that automates the generation of high-leverage agent prompts with surgical context, hard constraints, non-goals, and verification commands.

Learning objectives

  • Implement surgical file context bundling with markdown formatting.
  • Construct structured specification prompts with explicit boundaries.
  • Attach automated verification test gates to prompts.
  • Handle missing files and format constraints cleanly.

Prerequisites

  • Python 3.10+ installed
  • pytest installed

Supported operating systems

  • macOS, Linux, Windows WSL2

Hardware requirements

  • Standard CPU, 512MB RAM

Required software

  • Python 3.10+, pytest

Free and open-source options

  • Python Standard Library, Pytest

Installation

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements/requirements.txt

File structure

  • starter/spec_compiler.py: Starter implementation skeleton
  • examples/spec_compiler.py: Verified reference implementation
  • tests/test_spec_compiler.py: Test suite
  • expected-output/: Captured execution logs

How to run

python3 examples/spec_compiler.py

What the commands do

  • Compiles specification prompts, bundles context files, and verifies prompt formatting.

Expected output

## TASK OBJECTIVE
Refactor API

## SURGICAL CONTEXT
#### File: app.py (NOT FOUND)

## HARD CONSTRAINTS
- Speed up

## NON-GOALS (DO NOT MODIFY)
- Do not break tests

## VERIFICATION PLAN
Run the following c

Validation steps

Run test runner:

bash tests/run_tests.sh

Tests

The test suite validates:

  • Context file extraction and formatting
  • Missing file annotation
  • Constraint and non-goal list rendering
  • Complete prompt compilation containing all required sections

Cleanup

rm -rf .pytest_cache __pycache__ .venv

Troubleshooting

Ensure workspace root path is valid.

Security notes

Runs completely offline on local CPU.

Extension exercises

Implement an automatic token counter to measure context size.

Day number: 303 of 365

Expected output

FIELDS.md

# Measured Values
- `bundled_files`: 1
- `compiled_prompts`: 1

examples-run.txt

# TASK OBJECTIVE
Refactor API

# SURGICAL CONTEXT
### File: app.py (NOT FOUND)

# HARD CONSTRAINTS
- Speed up

# NON-GOALS (DO NOT MODIFY)
- Do not break tests

# VERIFICATION PLAN
Run the following c

measured-values.txt

bundled_files=1
compiled_prompts=1

run-output.txt

# TASK OBJECTIVE
Refactor API

# SURGICAL CONTEXT
### File: app.py (NOT FOUND)

# HARD CONSTRAINTS
- Speed up

# NON-GOALS (DO NOT MODIFY)
- Do not break tests

# VERIFICATION PLAN
Run the following c

starter-run.txt

An untouched starter fails the suite. Captured from a real run:

self = <examples.spec_compiler.SpecCompiler object at 0x108b90550>
goal = 'Add JWT Authentication', target_files = ['api.py']
constraints = ['Use pyjwt', 'Set 1h expiry']
non_goals = ['Do not change password hashing']
verification_command = 'pytest tests/test_auth.py'

    def compile_prompt(self, goal: str, target_files: List[str], constraints: List[str], non_goals: List[str], verification_command: str) -> str:
>       raise NotImplementedError('TASK 2: implement compile_prompt.')
E       NotImplementedError: TASK 2: implement compile_prompt.

examples/spec_compiler.py:20: NotImplementedError
=========================== short test summary info ============================
FAILED tests/test_spec_compiler.py::test_bundle_context_existing_files - NotI...
FAILED tests/test_spec_compiler.py::test_bundle_context_missing_file - NotImp...
FAILED tests/test_spec_compiler.py::test_compile_prompt_full_sections - NotIm...
============================== 3 failed in 0.03s ===============================

Implement each TASK in starter/, copy it over examples/, and the same
suite goes green.

test-output.txt

============================= test session starts ==============================
platform darwin -- Python 3.14.0, pytest-9.1.1, pluggy-1.6.0 -- <repo>/.venv-tools/bin/python3.14
cachedir: .pytest_cache
rootdir: <repo>/labs/sections/ai-engineering/day-303-working-with-a-coding-agent
plugins: cov-7.1.0, anyio-4.14.2
collecting ... collected 3 items

tests/test_spec_compiler.py::test_bundle_context_existing_files PASSED   [ 33%]
tests/test_spec_compiler.py::test_bundle_context_missing_file PASSED     [ 66%]
tests/test_spec_compiler.py::test_compile_prompt_full_sections PASSED    [100%]

============================== 3 passed in 0.01s ===============================

test-run.txt

============================= test session starts ==============================
platform darwin -- Python 3.14.0, pytest-9.1.1, pluggy-1.6.0 -- <repo>/.venv-tools/bin/python3.14
cachedir: .pytest_cache
rootdir: <repo>/labs/sections/ai-engineering/day-303-working-with-a-coding-agent
plugins: cov-7.1.0, anyio-4.14.2
collecting ... collected 3 items

tests/test_spec_compiler.py::test_bundle_context_existing_files PASSED   [ 33%]
tests/test_spec_compiler.py::test_bundle_context_missing_file PASSED     [ 66%]
tests/test_spec_compiler.py::test_compile_prompt_full_sections PASSED    [100%]

============================== 3 passed in 0.01s ===============================

Source files

examples/spec_compiler.py (1896 bytes)
import os
from typing import List

class SpecCompiler:
    def __init__(self, workspace_root: str):
        self.workspace_root = os.path.realpath(workspace_root)
        
    def bundle_context(self, relative_file_paths: List[str]) -> str:
        blocks = []
        for path in relative_file_paths:
            abs_path = os.path.join(self.workspace_root, path)
            if os.path.exists(abs_path):
                with open(abs_path, "r", encoding="utf-8") as f:
                    content = f.read()
                blocks.append(f"### File: {path}\n```python\n{content}\n```")
            else:
                blocks.append(f"### File: {path} (NOT FOUND)")
        return "\n\n".join(blocks)
        
    def compile_prompt(
        self,
        goal: str,
        target_files: List[str],
        constraints: List[str],
        non_goals: List[str],
        verification_command: str
    ) -> str:
        context_str = self.bundle_context(target_files)
        
        prompt_lines = [
            f"# TASK OBJECTIVE\n{goal}\n",
            f"# SURGICAL CONTEXT\n{context_str}\n",
            "# HARD CONSTRAINTS",
            "\n".join([f"- {c}" for c in constraints]),
            "\n# NON-GOALS (DO NOT MODIFY)",
            "\n".join([f"- {ng}" for ng in non_goals]),
            f"\n# VERIFICATION PLAN\nRun the following command to verify your work:\n`{verification_command}`\n",
            "# INSTRUCTION FOR AGENT",
            "1. Output your step-by-step implementation plan first.",
            "2. Apply targeted edits using search-and-replace chunks.",
            "3. Run the verification command and report test results."
        ]
        return "\n".join(prompt_lines)

if __name__ == "__main__":
    compiler = SpecCompiler(".")
    res = compiler.compile_prompt("Refactor API", ["app.py"], ["Speed up"], ["Do not break tests"], "pytest")
    print(res[:200])
metadata.yml (400 bytes)
lesson_id: D303
day: 303
kind: python
languages:
- python
setup_commands:
- pip install -r requirements/requirements.txt
run_commands:
- python examples/spec_compiler.py
test_commands:
- bash tests/run_tests.sh
cleanup_commands:
- rm -rf __pycache__ .pytest_cache
requires_network: false
requires_api_key: false
estimated_minutes: 45
last_executed: '2026-08-30'
executed_on: macOS 15.0 Apple Silicon
requirements/requirements.txt (14 bytes)
pytest>=7.0.0
starter/spec_compiler.py (991 bytes)
"""STARTER -- implement each TASK below, then run the tests.

Every function that raises NotImplementedError is yours to write. The
imports, constants and data structures are given; the logic is not.
Run `bash tests/run_tests.sh` to see which tasks are still outstanding.
"""

import os
from typing import List

class SpecCompiler:

    def __init__(self, workspace_root: str):
        self.workspace_root = os.path.realpath(workspace_root)

    def bundle_context(self, relative_file_paths: List[str]) -> str:
        raise NotImplementedError('TASK 1: implement bundle_context.')

    def compile_prompt(self, goal: str, target_files: List[str], constraints: List[str], non_goals: List[str], verification_command: str) -> str:
        raise NotImplementedError('TASK 2: implement compile_prompt.')
if __name__ == '__main__':
    compiler = SpecCompiler('.')
    res = compiler.compile_prompt('Refactor API', ['app.py'], ['Speed up'], ['Do not break tests'], 'pytest')
    print(res[:200])
tests/run_tests.sh (253 bytes)
#!/usr/bin/env bash
set -e
export PYTHONPATH=examples:.
if [ -n "$PYTEST" ]; then
    $PYTEST tests/test_*.py -v
elif command -v pytest &> /dev/null; then
    pytest tests/test_*.py -v
else
    python3 -m unittest discover -s tests -p 'test_*.py' -v
fi
tests/test_spec_compiler.py (1747 bytes)
import pytest
import tempfile
import os
from examples.spec_compiler import SpecCompiler

def test_bundle_context_existing_files():
    with tempfile.TemporaryDirectory() as tmpdir:
        sample = os.path.join(tmpdir, "models.py")
        with open(sample, "w", encoding="utf-8") as f:
            f.write("class User:\n    pass\n")
            
        compiler = SpecCompiler(tmpdir)
        context = compiler.bundle_context(["models.py"])
        assert "### File: models.py" in context
        assert "class User:" in context

def test_bundle_context_missing_file():
    with tempfile.TemporaryDirectory() as tmpdir:
        compiler = SpecCompiler(tmpdir)
        context = compiler.bundle_context(["missing.py"])
        assert "### File: missing.py (NOT FOUND)" in context

def test_compile_prompt_full_sections():
    with tempfile.TemporaryDirectory() as tmpdir:
        fpath = os.path.join(tmpdir, "api.py")
        with open(fpath, "w", encoding="utf-8") as f:
            f.write("def login(): pass\n")
            
        compiler = SpecCompiler(tmpdir)
        prompt = compiler.compile_prompt(
            goal="Add JWT Authentication",
            target_files=["api.py"],
            constraints=["Use pyjwt", "Set 1h expiry"],
            non_goals=["Do not change password hashing"],
            verification_command="pytest tests/test_auth.py"
        )
        
        assert "# TASK OBJECTIVE\nAdd JWT Authentication" in prompt
        assert "### File: api.py" in prompt
        assert "- Use pyjwt" in prompt
        assert "- Set 1h expiry" in prompt
        assert "- Do not change password hashing" in prompt
        assert "`pytest tests/test_auth.py`" in prompt
        assert "# INSTRUCTION FOR AGENT" in prompt

Troubleshooting

Troubleshooting - Day 303

Verify all relative paths exist in workspace root.

Security notes

Security - Day 303

Sanitize context bundles to prevent accidental credential leakage.