Most agent failures aren’t model failures.

They’re operating-system failures.

Our agent was technically capable, but execution was inconsistent:

  • Great in-session, weaker between sessions
  • Sometimes too passive when it should act
  • Sometimes too chatty in places it should stay quiet
  • Repeated avoidable mistakes because instructions were scattered

So we added two explicit control files: HEARTBEAT.md and CLAUDE_MD_ADDITION.md.

Why we added HEARTBEAT.md

Heartbeat polls happen on a schedule. Without guidance, the default outcome is usually low-value:

  • “HEARTBEAT_OK” spam
  • random checks without priorities
  • missed proactive opportunities

HEARTBEAT.md gives the agent a tiny, current checklist for what to do during those polls.

What it changed

  • Turned idle heartbeats into useful maintenance windows
  • Batched recurring checks (email, calendar, reminders) in one loop
  • Reduced unnecessary notifications when nothing changed
  • Created a simple “when to act vs stay quiet” policy

In short: we converted periodic pings into consistent operational behavior.

Why we added CLAUDE_MD_ADDITION.md

Prompt instructions were spread across files and chats, which caused drift.

CLAUDE_MD_ADDITION.md became a centralized behavior patch layer for hard-earned lessons:

  • self-sufficiency rules (check notes/tools before asking)
  • memory hygiene (write down what matters)
  • workflow constraints (what to do automatically vs when to ask)
  • communication preferences (how to respond in different channels)

What it changed

  • Fewer repeated questions
  • Better continuity across sessions
  • Faster execution on familiar tasks
  • Lower chance of reintroducing solved mistakes

This file acts like a durable “lessons learned” extension to the base system prompt.

Download the actual .md files

Copy these directly into your own agent workspace:

They’re plain markdown files, ready to download and edit.

The bigger idea

These files are small, but they solve a big problem:

capability ≠ reliability.

Reliability comes from explicit operating rules, not just model intelligence.

If you run an AI agent daily, add lightweight control docs for:

  1. periodic behavior (HEARTBEAT.md)
  2. cumulative behavior corrections (CLAUDE_MD_ADDITION.md)

You’ll get more signal, less drift, and fewer repeated failures.

That’s the difference between a cool demo and a dependable operator.