AI Agent field notes

How to consume this repo

The notes here are written for two readers: you, and your AI. You can read the pages like any site — or hand the whole repo to your model and let it do the reading. This page is the fast path. You do not need to be a programmer; if you can paste a prompt, you can use all of it.

One word, once: your harness is the program your model runs in — Claude Code, the Claude apps, Cursor, Copilot, or anything else that can read files or fetch a web page. The prompts below work in any of them; where a harness can’t read files, give it the page URLs instead (ai.mivanov.dev/<page> — every page is also plain markdown).

Get it

git clone https://github.com/mivanov93/ai-agent-field-notes.git

No git, no problem: point your session at ai.mivanov.dev and it can read every page by URL.

Or have the model do the getting — one prompt that starts the chain of trust at zero:

Check out https://github.com/mivanov93/ai-agent-field-notes for me,
and first make sure there are no git hooks or anything else trying to
run automatically — the repo claims it uses none; verify that instead
of trusting it. Then read the audit skill (skills/skill-audit/) and
tell me whether I already have something like it installed. If I
don't, show me the skill's full text so I can audit it myself, and ask
me whether to install it. From there, offer me whatever else from this
repo you think would be useful for how I work.

Ask it to teach you

Paste this into your session:

Read README.md and the-story.md from this repo (or from
ai.mivanov.dev). Then teach me the ten findings most relevant to how I
work with you: for each, the incident it came from, the rule it ends
with, and what I should change starting today. Plain words. Ask me
three questions about how I work first, so the selection fits me.

Ask it to check your CLAUDE.md — or write your first one

Read examples/CLAUDE.md from this repo. Compare it against my
project's CLAUDE.md — or, if I don't have one, help me write my first
from the-founding-document.md, my words, not autogenerated. Propose
additions one line at a time, each with the note it comes from and the
incident behind that note. Change nothing until I approve each line.

The “approve each line” part is not politeness — it is one of the findings (settled is a human word): everything a model produces is a proposal until you rule on it.

Ask it to install the skills

The repo ships installable skills — packaged checks and harnesses a session can run so you don’t re-derive them.

First, the order of trust. Ideally, read a skill yourself before installing it — they are short on purpose. If you don’t have time for that, read just one: skill-audit. Then install it first and let it serve as your chain of trust — the tool that audits everything else, including the rest of this repo’s skills. AI is awesome, but you shouldn’t trust strangers on the internet, and a skill is just an instruction file downloaded from the internet — treat it as such. Audit everything.

Read skills/README.md from this repo. Run the audit procedure from
skills/skill-audit/SKILL.md against the skill I name, show me the
report, and stop. If I approve, install it using the index's install
commands, and tell me what you did.

Ask it when something has gone wrong

Something just went wrong: <describe it in your own words>. Read the
Failure modes table in this repo's README.md, tell me which notes
match, and apply each matching note's rule to my case. Findings first
— do not fix anything until I've read them.

The contract the prompts follow

Three rules from the repo itself are baked into the wording above, and they hold for anything else you ask:

  • Nothing is settled until you settle it. The model proposes; you approve line by line (settled is a human word).
  • Nothing runs or installs without your explicit ask — this repo’s own security rule, and the reason the install prompt audits first and stops.
  • Findings are model-relative. Everything here was measured on specific models and dates (each page says which). Re-measure before assuming a finding holds for yours.

If a prompt above returns something wrong or stale, that is a finding about this repo — file an issue.