AI Engineering: Agents and Applications › AI Coding Agents › Day 303
Hands-on lab — Day 303: Working with a Coding Agent
- ← Back to the Day 303 lesson
- Open the hands-on files on GitHub — clone or download them from the public labs repository
- Local path in your clone:
labs/sections/ai-engineering/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
- Lesson title: Working with a Coding Agent
- Day number: 303 of 365
- Lesson article: https://ai-roadmap-365.github.io/day-303-working-with-a-coding-agent
- Lab files: everything you need is in this directory — follow “How to run” below.
- Browse the course locally: from the repository root, this lab also appears in the course website at
/labs/day-303-working-with-a-coding-agentwhen the site is running.
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 skeletonexamples/spec_compiler.py: Verified reference implementationtests/test_spec_compiler.py: Test suiteexpected-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.
Navigation
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.