Build Your Harness
Picture a new engineer joining your medical device team. On day one, they can read code, they can grep, they can write functions that compile. But they can’t tell you which modules are safety-critical, which parts of the codebase have bitten you three times, why one function has an odd signature, or what breaks if you touch the dosing calculation.
An AI coding assistant on your codebase today has roughly the same handicap. It can read, grep, and write. It doesn’t know what’s safety-critical, what’s history, what’s convention, what’s load-bearing. Every developer on your team is holding that context in their head. The AI isn’t.
The harness is how you give the AI the same context your team already has. Not a document for the auditors. A small set of files the AI reads on every session, so it stops behaving like a new hire and starts behaving like someone who’s been on the team for a year.
Four things developers actually do all day
Most of a working day on a medical device codebase isn’t “write a new feature from scratch.” It’s something smaller and more frequent. Four activities carry most of the load. Each one looks completely different with and without a harness.
1. Making a code change
A developer picks up a ticket: “add a safety check that prevents dosing above the configured max rate.”
Without a harness, the AI reads the ticket and whatever files it can see. It produces a plausible function. Whether that function lands in the right module, uses your logging helper, follows your error-handling convention, carries a traceability tag, or has a test shaped like your other tests, all of that depends on whether the developer thought to prompt for each one. Usually they didn’t. The AI’s output ships close to right, the PR reviewer catches the inconsistencies, and the loop drags.
With a harness, the AI reads AGENTS.md and knows: dosing math lives in src/dosing/, safety-critical modules require a @req tag linking to a requirement, errors go through src/log/log_audited.c, no malloc after boot. The function it produces fits where it lands. The test it drafts links to the right requirement. The PR goes in and the review focuses on the actual change, not on cleanup.
The win isn’t “faster code”. It’s code that already matches what the second reviewer would have asked for.
2. Understanding an existing module
A developer gets paged to a bug in src/motor/. They’ve never touched the module. They need to understand it fast.
Without a harness, they ask the AI “what does src/motor/ do?” The AI reads the files and gives back a structural summary: function names, their arguments, which calls which. Useful, but shallow. It doesn’t know the module is Class C, that the PID loop was tuned on a specific motor part, that there’s a known workaround for a hardware revision bug, or that the odd comment on line 142 is there because someone fixed a real-world oscillation two years ago.
With a harness, the AI has read src/motor/NOTES.md, a short file the team keeps alongside the code. That file says what the module does in plain terms, which hardware it was tuned for, the top three gotchas, and the handful of past incidents that explain the shape of the code. The AI’s answer now sounds like something a senior engineer who’d worked on this module would say. The developer gets up to speed in minutes instead of a day.
3. Impact assessment: “what breaks if I change this?”
A developer wants to change the max-rate constant. They need to know what else is affected before they touch it.
Without a harness, they ask the AI to find references. It greps. It returns the twelve places the constant is used. Fine. But it doesn’t know that six of those usages are in Class C modules, that the constant is referenced in requirement SR-134, that hazard HR-042 lists it as a control measure, or that the acceptance test for dosing uses it as a boundary. The developer has to piece all of that together manually, or risk missing something.
With a harness, the AI knows module classifications from AGENTS.md, knows traceability lives in the @req tags on each function, and knows the risk file references constants by name. The answer the developer gets looks like:
This constant is used in 12 places. Six are in Class C modules (safety, dosing, motor). It is called out in requirement SR-134 and listed as a control measure for hazard HR-042. Three test cases use it as a boundary. If you change the value, the risk file needs re-review and these tests need to re-run: …
That’s an impact assessment, not a grep.
4. Understanding a feature end to end
A developer is asked to extend a feature. They need to understand the whole thing before adding to it: the requirement, the design decision, the code, the tests, the risks, the known limitations.
Without a harness, this is a two-day scavenger hunt. Confluence, Jira, the DHF, and the code are in four different places. The AI can read the code but can’t follow the trail.
With a harness, the trail lives inside the repo. Requirements in docs/req/, ADRs in docs/dhf/adr/, risk entries in risk/hazard-analysis.md, tests tagged by requirement ID. The AI can walk from the requirement to the ADR to the code to the tests to the risk entry, all in one session, and summarise the feature’s full picture. The developer starts the actual work in an hour, with the right context, instead of in two days with incomplete context.
src/motor/ well enough to safely change it? If the answer is a week, your AI is in exactly the same position. The harness is the cheat sheet you'd give the engineer, written down and loaded automatically.
Where the context actually lives
The harness isn’t one big file. It’s a handful of small, well-placed ones.
Project-level AGENTS.md
A plain Markdown file at the repo root. Standing facts the AI should know on every session: what the product is, its safety classification, folder layout, conventions, banned patterns, how to run tests, SOUP policy. Keep it under 120 lines. If it reads like a policy document, it’s too long.
A tight example for a Class C firmware project:
# Project: Infusion Pump Firmware
Intended use: controlled IV medication delivery.
Safety classification: Class C per IEC 62304.
## Folder layout
- src/safety/ Class C safety modules (two reviewers required)
- src/motor/ motor control, Class C
- src/dosing/ dose calculation, Class C
- src/comm/ Class B
- src/log/ audited logging (never use printf)
- tests/ mapped to requirements in docs/req/
- docs/req/ software requirements
- docs/dhf/adr/ architecture decision records
- risk/ risk management (hazard-analysis.md)
## Conventions
- Every function in src/ carries a @req tag with a requirement ID
- No malloc after boot; all memory allocated during init
- Use src/log/log_audited.c for all logging
- Changes to src/safety/ require a documented risk reassessment
## Banned
- No eval, exec, dynamic code loading
- No new third-party dependency without a SOUP evaluation
- No logging of patient data at any level
Module-level NOTES.md
This is the file nobody writes but everybody wishes existed. A short file inside each important src/ folder. A page or less. What this module does in plain terms, which hardware or protocol it depends on, the gotchas, the past incidents that shaped the code. The AI reads it when the developer is working in that folder. New engineers read it on their first day.
A src/motor/NOTES.md might say:
# Module: Motor Control
Drives the stepper motor that controls the plunger. Runs a PID loop
tuned for the Faulhaber 1016-SR at 4V nominal.
## Gotchas
- PID gains in motor_pid.c were tuned on hardware rev 2.3. Rev 2.1
units (serial < 20000) oscillate at startup; see the startup ramp
in motor_init().
- The current-sense ADC saturates near full stall. The clamp in
motor_read_current() isn't paranoia, it's protecting against an
off-by-one that caused a recall in 2022 (incident I-087).
- Don't call motor_set_rate() from an ISR. It allocates on the rate
queue and that's not ISR-safe.
That one file turns the next hour of debugging into the next ten minutes. And it turns the AI’s generic answers into answers that know about I-087.
Skills for recurring procedures
One file per procedure the team does over and over. Code review, impact assessment, writing an ADR, cutting a release. Each file tells the AI how your team does that specific thing.
An impact-assessment skill might say: “For any change under src/safety/, src/motor/, or src/dosing/, produce structured output: files affected, requirements referenced, tests to re-run, risk entries to review.” Now every impact assessment the AI gives you comes back with the same shape, every time, no matter which developer asked.
Hooks as the stop-ship layer
Pre-commit runs the linter, the banned-pattern scan, and the fast tests. Pre-push verifies every @req tag resolves to a real requirement file. Pre-release checks that the DHF has entries for every merged ADR and the SBOM is current. Hooks are the smallest layer, but the only one the AI can’t talk its way around.
Keep it alive
A harness is only as useful as its freshness. A stale NOTES.md isn’t just a bug, it’s a liability: the AI will cheerfully repeat the stale guidance to the next developer, and the next one, and the next one. The engineer who onboards six months from now will learn the wrong thing with confidence.
Treat AGENTS.md, NOTES.md, and your skill files as controlled documents. Update them in the same PR as the process or module change they describe. When a NOTES.md points at an incident that got closed out, update the file. When a module gets re-tuned for new hardware, update the gotchas. Give someone the explicit role of harness owner for the quarter and rotate it.
The one line
A good harness isn’t a document. It’s a scattered set of small files that give the AI the same context your team already has in its heads. The payoff is that the AI stops reading your codebase like a stranger and starts reasoning about it like a teammate who’s been there a year.
Write the AGENTS.md. Then write a NOTES.md for the module you touch most often. Then let the AI help with the work.
Was this useful? A quick tap tells me what to write more of.
Anonymous. No accounts, no tracking beyond a per-browser vote guard.