the agent starts Inputs Outputs Edge cases File type, columns, size Format, columns, where it’s saved Redirects, trailing slashes, parameters, empty cells Acceptance criteria Constraints Focus What must be true for it to count as done Rate limits, allowed libraries, API access One job per request (“build my audit tool” is several).
VAGUE SCOPED “Map old URLs to new URLs.” “Given old.csv and new.csv, match each old URL to its closest new URL by path similarity. Flag matches under 0.7 confidence for manual review. Output redirects.csv with old, new, score and flag columns.”
any code ASK 1 What files will be created? 2 What’s the approach? 3 What questions or decisions are still open? PLAN.md Save it as markdown Easy to reference, easy to amend. And you get a history of where you’ve been.
context Give it current information Start new conversations Up-to-date docs and examples wherever you can, so it isn’t guessing from old training data Long threads pile up contradictions and changed directions (yours and the agent’s)
can live WHERE THINK OF IT AS USE IT FOR CLAUDE.md / AGENTS.md Your onboarding doc The project, its commands, standing rules. Keep it under 200 lines. Skills The SOP binder Specific tasks or processes Path-scoped rules (.claude/rules/) Special notes Client or internal project specifics Hooks Access rules Checks that run automatically, like blocking edits to .env
and what moves it Working directory Staging area Local repository Files you and the agent are editing Changes picked for the next snapshot Saved snapshots: your undo points Remote repository Shared copy on GitHub or GitLab git add git commit git push git restore git pull
reversible Small commits New idea? New branch. Easy to undo, easy to find exactly what changed later Same for a new feature. Main stays the version that works. .gitignore. Always. Messages that mean something Secrets, data and caches never get committed “Add retry logic to GSC fetch,” not “fix”
a quick look Moved goalposts Hardcoded values An acceptance threshold drops from 0.7 to 0.5 Written straight into the code instead of using your variables New dependencies Tests edited to pass Packages added to the project without asking The test changed, not the code HABITS Don’t understand a change? Ask the agent what it changed. Keep changes small so they’re easy to review.
way out GUARDRAIL WHAT IT MEANS Crawl limits Crawl depth, max page count, and a set of visited URLs so nothing gets revisited Crawl traps Faceted navigation, calendars, session IDs, parameter combos Redirects Cap how many you follow Timeouts On every request Rate and retry limits Don’t hammer a server or retry forever
sample first Keep a sample with expected results A handful of rows where you already know the right answer Use it to train the agent, too Give it the sample up front so it knows what good output looks like
to get started 1 Save real examples 2 Don’t start from scratch 3 Document the bugs you find Pages and API responses your tool handles, in a tests folder Serge Bezborodov built openseotest.org - sample pages and scenarios for testing SEO issues And write a test for each one
for everything that works Every working output gets a test, so you know the moment it breaks Expect dozens (potentially hundreds) Idempotency: running twice on the same input gives the same result, not duplicate rows EXAMPLE You add parameter URL support to a redirect mapper, and 40 previously correct matches change. The comparison shows exactly which 40, so you can review them and decide which ones are actually wrong.
at the edges LIBRARIES Validate on load Validate before saving Fail LOUDLY, and name what failed pydantic Checks individual records against a defined structure (really handy for API responses) Audit how many rows passed and failed Check totals against the source pandera Checks entire data sets
golden set Golden set: a small, hand-labeled sample you’ve checked yourself, used to measure how often the model gets it right Set size Track accuracy 50 to 200 records Over time, so you know it’s getting better (not worse) Structured outputs Wherever possible Log every run Model name, prompt version, cost per run
haven’t run into before Hallucinated packages Prompt injection Agents sometimes suggest packages that don’t exist. Attackers register those names with malicious code. Pages, documents and API responses can carry hidden instructions. And we fetch other people’s HTML for a living. Also known as “slopsquatting”
the agent didn’t get from you Check the package Lean on well-known libraries It exists, it’s spelled right, and people actually use it Over the obscure one nobody’s heard of Fetched content is data Use a lockfile Tell your agent to treat everything a script fetches as data, not instructions So dependency versions don’t randomly change on you
secrets out of your code .gitignore, again Secrets live in .env Add a secret scanner Your .env and credential files go in it before the first commit Never hardcoded in the script gitleaks or detect-secrets , as a pre-commit hook
## Definition of done Do not tell me a task is done until: 1. The tests pass 2. It runs end to end on data/sample/ If something fails and you can’t fix it, tell me. Don’t report success.
runs on my laptop No Personal tool Can a teammate run it from a clean machine? No Fix this first Is the output tested against known-good data? No Add tests first Does production depend on it? Yes Bring in engineering Does anyone else use it? Good to go. Keep it in git. Yes README, lockfile, .env. Then ask again. Yes Before anyone relies on it. Then ask again. Yes No Team tool: share it, you maintain it Scheduled, live site or revenue: pair, review, hand off
samtorres
speedyindexteam
aleyda
joshbly
joss1
portentint
osbplyp5611
chrisleverseo
charlesmeaden
clarasoteras
.jpg){kind=avatar}
cargoodrich
destraynor
varn
mfonobong
techseoconnect
addyosmani
jonoalderson
eileencodes
holman
keithpitt
akosma
baasie
