DeepSeek Harness Doesn't Bet on AI Understanding Your Code — It Writes the Rules Down
Most teams stuff AI coding rules into one ever-growing prompt file that nobody reads. Separating permanent constraints, task procedures, and design rationale — and enforcing at least one rule through CI — turns AI development guidelines from aspirational text into actual engineering constraints.
The open-source DeepSeek Harness repository contains a hidden `.agents/` directory that reveals a systematic approach to AI-assisted development. Instead of relying on a single massive prompt, it separates long-term rules (AGENTS.md), task procedures (Skills), and design rationale (Agent Notes) into distinct, loadable units. The root AGENTS.md enforces concrete, verifiable rules like "Model-visible content must be logged," while directory-specific AGENTS.md files prevent context bloat by scoping rules to the relevant code area.
The 684 Agent Notes are categorized by status — proposed, implemented, rejected, archived — and each one must document alternatives considered, not just the final decision. This prevents AI (and new team members) from re-proposing solutions that were already evaluated and discarded. A detailed case study of the ACP snapshot testing Note shows how the system records not just what was built, but the explicit boundaries of what the solution does and doesn't cover.
For smaller projects, copying the full system would be overkill. The core insight worth adopting is the separation of concerns: rules that are always true, procedures for specific tasks, and short decision records that capture rejected paths. Even a minimal setup with one enforceable AGENTS.md, two Skills, and a decision template connected to CI is more effective than endlessly refining a single prompt.
Separating AI development rules into permanent constraints, procedural Skills, and decision records solves a problem most teams don't even recognize: that a single massive prompt file becomes ignored background noise.
The mandatory "Alternatives considered" section in every Agent Note is more valuable than the final decision itself, because it prevents both humans and AI from re-litigating already-resolved trade-offs.
Snapshot replay testing that replaces only the unstable model layer while keeping the real Loader, Agent Loop, and persistence is a pragmatic middle ground between brittle mocks and expensive live API tests.
Restricting certain Skills to explicit user invocation acknowledges that AI agents lack the judgment to decide when a high-cost or high-impact operation is appropriate — a constraint most AI-coding setups ignore.
The system's value isn't in making AI write perfect code, but in making it hard for AI to bypass architecture, skip design records, or declare completion after minimal testing.
Starting with one enforceable AGENTS.md rule connected to CI is more effective than writing hundreds of Notes, because unenforced specifications decay into ignored files regardless of their quality.