<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: Pluto</title>
    <description>The latest articles on DEV Community by Pluto (@mars_peakul).</description>
    <link>https://dev.to/mars_peakul</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F4181312%2F0ffae6e3-1922-4a01-b900-828b6ef353e9.jpg</url>
      <title>DEV Community: Pluto</title>
      <link>https://dev.to/mars_peakul</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/mars_peakul"/>
    <language>en</language>
    <item>
      <title>How to get correct SQL from AI: give it the schema, the dialect, and EXPLAIN</title>
      <dc:creator>Pluto</dc:creator>
      <pubDate>Mon, 19 Oct 2026 02:42:12 +0000</pubDate>
      <link>https://dev.to/mars_peakul/how-to-get-correct-sql-from-ai-give-it-the-schema-the-dialect-and-explain-nfm</link>
      <guid>https://dev.to/mars_peakul/how-to-get-correct-sql-from-ai-give-it-the-schema-the-dialect-and-explain-nfm</guid>
      <description>&lt;p&gt;AI tools are genuinely good at writing SQL. Ask ChatGPT, Claude, Cursor or Claude Code for "monthly revenue per plan" and you'll have a query in seconds, and it will probably run.&lt;/p&gt;

&lt;p&gt;That's the problem. Wrong SQL rarely fails loudly. It returns a number, and the number looks plausible. Here are the mistakes I see most often in AI-written SQL, why they happen, and the three inputs that fix most of them: &lt;strong&gt;the schema, the dialect, and the plan&lt;/strong&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why the model gets it wrong
&lt;/h2&gt;

&lt;p&gt;The model isn't careless. It's missing information:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;It hasn't seen your schema, so it writes the column names that are &lt;em&gt;usually&lt;/em&gt; there (&lt;code&gt;users.created_at&lt;/code&gt;, &lt;code&gt;orders.customer_id&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;It doesn't know your engine, so it mixes PostgreSQL, MySQL and SQLite syntax, or uses syntax that runs on both with different results.&lt;/li&gt;
&lt;li&gt;It doesn't know what "last month", "active" or "revenue" mean in your business, so it picks something and doesn't tell you.&lt;/li&gt;
&lt;li&gt;It can't see your data, so it doesn't know which columns contain NULLs or which joins are one-to-many.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Each of those turns into a specific, recognisable bug.&lt;/p&gt;

&lt;h2&gt;
  
  
  Bug 1: fan-out (totals that are too high)
&lt;/h2&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="c1"&gt;-- "Revenue per plan from subscription invoices"&lt;/span&gt;
&lt;span class="k"&gt;SELECT&lt;/span&gt; &lt;span class="n"&gt;i&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;plan_id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;SUM&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;i&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;amount_cents&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;AS&lt;/span&gt; &lt;span class="n"&gt;revenue_cents&lt;/span&gt;
&lt;span class="k"&gt;FROM&lt;/span&gt; &lt;span class="n"&gt;invoices&lt;/span&gt; &lt;span class="n"&gt;i&lt;/span&gt;
&lt;span class="k"&gt;JOIN&lt;/span&gt; &lt;span class="n"&gt;invoice_lines&lt;/span&gt; &lt;span class="n"&gt;l&lt;/span&gt; &lt;span class="k"&gt;ON&lt;/span&gt; &lt;span class="n"&gt;l&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;invoice_id&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;i&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt;
&lt;span class="k"&gt;WHERE&lt;/span&gt; &lt;span class="n"&gt;l&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;kind&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s1"&gt;'subscription'&lt;/span&gt;
&lt;span class="k"&gt;GROUP&lt;/span&gt; &lt;span class="k"&gt;BY&lt;/span&gt; &lt;span class="n"&gt;i&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;plan_id&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If an invoice has three subscription lines, its total is summed three times. The query runs, the number is wrong, and nothing warns you. The fix is to stop joining at the wrong grain:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;SELECT&lt;/span&gt; &lt;span class="n"&gt;i&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;plan_id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;SUM&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;i&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;amount_cents&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;AS&lt;/span&gt; &lt;span class="n"&gt;revenue_cents&lt;/span&gt;
&lt;span class="k"&gt;FROM&lt;/span&gt; &lt;span class="n"&gt;invoices&lt;/span&gt; &lt;span class="n"&gt;i&lt;/span&gt;
&lt;span class="k"&gt;WHERE&lt;/span&gt; &lt;span class="k"&gt;EXISTS&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="k"&gt;SELECT&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt; &lt;span class="k"&gt;FROM&lt;/span&gt; &lt;span class="n"&gt;invoice_lines&lt;/span&gt; &lt;span class="n"&gt;l&lt;/span&gt;
  &lt;span class="k"&gt;WHERE&lt;/span&gt; &lt;span class="n"&gt;l&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;invoice_id&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;i&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt; &lt;span class="k"&gt;AND&lt;/span&gt; &lt;span class="n"&gt;l&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;kind&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="s1"&gt;'subscription'&lt;/span&gt;
&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;GROUP&lt;/span&gt; &lt;span class="k"&gt;BY&lt;/span&gt; &lt;span class="n"&gt;i&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;plan_id&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A model can only spot this if it knows &lt;code&gt;invoices&lt;/code&gt; → &lt;code&gt;invoice_lines&lt;/code&gt; is one-to-many, which means it needs the schema with its keys.&lt;/p&gt;

&lt;h2&gt;
  
  
  Bug 2: NULLs that silently remove rows
&lt;/h2&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="c1"&gt;-- "Customers who have never ordered"&lt;/span&gt;
&lt;span class="k"&gt;SELECT&lt;/span&gt; &lt;span class="n"&gt;id&lt;/span&gt; &lt;span class="k"&gt;FROM&lt;/span&gt; &lt;span class="n"&gt;customers&lt;/span&gt;
&lt;span class="k"&gt;WHERE&lt;/span&gt; &lt;span class="n"&gt;id&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;IN&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;SELECT&lt;/span&gt; &lt;span class="n"&gt;customer_id&lt;/span&gt; &lt;span class="k"&gt;FROM&lt;/span&gt; &lt;span class="n"&gt;orders&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If any &lt;code&gt;orders.customer_id&lt;/code&gt; is NULL, &lt;code&gt;NOT IN&lt;/code&gt; is never true and this returns &lt;strong&gt;zero rows&lt;/strong&gt;. &lt;code&gt;NOT EXISTS&lt;/code&gt; doesn't have that problem:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;SELECT&lt;/span&gt; &lt;span class="k"&gt;c&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt; &lt;span class="k"&gt;FROM&lt;/span&gt; &lt;span class="n"&gt;customers&lt;/span&gt; &lt;span class="k"&gt;c&lt;/span&gt;
&lt;span class="k"&gt;WHERE&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;EXISTS&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;SELECT&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt; &lt;span class="k"&gt;FROM&lt;/span&gt; &lt;span class="n"&gt;orders&lt;/span&gt; &lt;span class="n"&gt;o&lt;/span&gt; &lt;span class="k"&gt;WHERE&lt;/span&gt; &lt;span class="n"&gt;o&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;customer_id&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="k"&gt;c&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Related traps: &lt;code&gt;status &amp;lt;&amp;gt; 'cancelled'&lt;/code&gt; also drops rows where &lt;code&gt;status&lt;/code&gt; is NULL; &lt;code&gt;COUNT(col)&lt;/code&gt; skips NULLs while &lt;code&gt;COUNT(*)&lt;/code&gt; doesn't; &lt;code&gt;SUM&lt;/code&gt; over no rows returns NULL, not 0. The model needs to know which columns are nullable, so give it the DDL, not a summary.&lt;/p&gt;

&lt;h2&gt;
  
  
  Bug 3: the wrong dialect
&lt;/h2&gt;

&lt;p&gt;Some differences fail loudly (&lt;code&gt;date_trunc&lt;/code&gt; doesn't exist in MySQL; MySQL has no &lt;code&gt;RETURNING&lt;/code&gt;). The dangerous ones run fine and return different results:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;7 / 2&lt;/code&gt; is &lt;code&gt;3&lt;/code&gt; in PostgreSQL and SQLite, &lt;code&gt;3.5000&lt;/code&gt; in MySQL.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;LIKE&lt;/code&gt; is case-sensitive in PostgreSQL, case-insensitive for ASCII by default in SQLite, and collation-dependent in MySQL.&lt;/li&gt;
&lt;li&gt;NULLs sort last in ascending order in PostgreSQL and first in MySQL and SQLite.&lt;/li&gt;
&lt;li&gt;Upserts: &lt;code&gt;ON CONFLICT ... DO UPDATE&lt;/code&gt; in PostgreSQL and SQLite (3.24+), &lt;code&gt;ON DUPLICATE KEY UPDATE&lt;/code&gt; in MySQL.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Tell the model the engine &lt;strong&gt;and version&lt;/strong&gt;. "MySQL" isn't enough: window functions and CTEs arrived in MySQL 8.0, &lt;code&gt;EXCEPT&lt;/code&gt; in 8.0.31.&lt;/p&gt;

&lt;h2&gt;
  
  
  Fix 1: give it the schema (the real one)
&lt;/h2&gt;

&lt;p&gt;Build a context block once and reuse it. Get the DDL straight from the database:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;PostgreSQL: &lt;code&gt;pg_dump --schema-only -t orders -t invoices ...&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;MySQL: &lt;code&gt;SHOW CREATE TABLE orders;&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;SQLite: &lt;code&gt;.schema orders&lt;/code&gt; in the &lt;code&gt;sqlite3&lt;/code&gt; shell&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Keep nullability, foreign keys, unique constraints and composite index column order. Add rough row counts and your conventions (soft-delete column, tenant column, time zone of timestamps). In Cursor, Claude Code or Codex, save it as a file in the repo (&lt;code&gt;docs/db-context.md&lt;/code&gt;) and reference it from your rules file so it's loaded every time.&lt;/p&gt;

&lt;h2&gt;
  
  
  Fix 2: make it state the spec before the SQL
&lt;/h2&gt;

&lt;p&gt;Most wrong reports are wrong because of an unstated definition, not bad syntax. Here's the prompt I start with:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;You are a senior SQL developer. Write ONE query for the exact engine and version below.

Engine: [ENGINE AND VERSION]
Schema (use only these tables and columns; if something is missing, say so):
[DDL]

Question: [QUESTION]
Definitions: [e.g. "month = calendar month in UTC", "exclude deleted_at IS NOT NULL"]

Before writing SQL:
1. State the grain (one output row per what), filters, and the time window as
   &amp;gt;= start AND &amp;lt; end.
2. List your assumptions. If one would change the answer materially, ask me.
3. Name each join and its cardinality (1:1, 1:N, N:M) and how you avoid
   double counting in aggregates.
Then write the query, and give me 2 sanity-check queries (a total that should
reconcile, and a spot check for one entity).

Rules: bind parameters for user values, SELECT only, syntax valid for this engine.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The "join cardinality" step catches fan-out. The "assumptions" step catches the definitions. The sanity checks give you something to run instead of something to trust.&lt;/p&gt;

&lt;h2&gt;
  
  
  Fix 3: ground performance advice in EXPLAIN
&lt;/h2&gt;

&lt;p&gt;"Add an index on every column in the WHERE clause" is what you get when the model has no plan to look at. Give it one:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;PostgreSQL:&lt;/strong&gt; &lt;code&gt;EXPLAIN (ANALYZE, BUFFERS) &amp;lt;query&amp;gt;;&lt;/code&gt; (from PostgreSQL 18, buffer counts are included with &lt;code&gt;ANALYZE&lt;/code&gt; automatically).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;MySQL 8:&lt;/strong&gt; &lt;code&gt;EXPLAIN FORMAT=TREE &amp;lt;query&amp;gt;;&lt;/code&gt; for the plan, &lt;code&gt;EXPLAIN ANALYZE &amp;lt;query&amp;gt;;&lt;/code&gt; (8.0.18+) for actual timings.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;SQLite:&lt;/strong&gt; &lt;code&gt;EXPLAIN QUERY PLAN &amp;lt;query&amp;gt;;&lt;/code&gt; (look for &lt;code&gt;SCAN&lt;/code&gt; vs &lt;code&gt;SEARCH ... USING INDEX&lt;/code&gt;).&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;One warning: &lt;code&gt;EXPLAIN ANALYZE&lt;/code&gt; &lt;strong&gt;executes&lt;/strong&gt; the statement in PostgreSQL and MySQL. For an &lt;code&gt;UPDATE&lt;/code&gt; or &lt;code&gt;DELETE&lt;/code&gt;, wrap it in a transaction and roll back, and do it on a copy of the data when you can.&lt;/p&gt;

&lt;p&gt;Then ask the model to walk the plan node by node and to cite the node behind every claim. In PostgreSQL plans, tell it that actual time and rows are per loop, so a cheap-looking inner node with &lt;code&gt;loops=50000&lt;/code&gt; may be where the time goes. Ask it to flag estimated-vs-actual row mismatches (often a statistics problem, not an index problem) and sorts that spill to disk. And get the plan from production-like data: the planner picks different plans for a thousand rows than for ten million.&lt;/p&gt;

&lt;h2&gt;
  
  
  Before you run any of it
&lt;/h2&gt;

&lt;p&gt;AI-written SQL that only reads is low risk. AI-written DDL and DML deserves a rule: &lt;strong&gt;nobody runs it on production without reading every statement.&lt;/strong&gt; In practice:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Run it on a local or staging copy first.&lt;/li&gt;
&lt;li&gt;Run the &lt;code&gt;WHERE&lt;/code&gt; of every &lt;code&gt;UPDATE&lt;/code&gt;/&lt;code&gt;DELETE&lt;/code&gt; as a &lt;code&gt;SELECT COUNT(*)&lt;/code&gt; before running the write.&lt;/li&gt;
&lt;li&gt;Wrap writes in a transaction and check the row count before &lt;code&gt;COMMIT&lt;/code&gt;. (PostgreSQL and SQLite DDL is transactional; MySQL DDL commits implicitly and can't be rolled back.)&lt;/li&gt;
&lt;li&gt;Use a read-only role for exploration, and set a statement timeout.&lt;/li&gt;
&lt;li&gt;Don't give coding agents production database credentials.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  The short version
&lt;/h2&gt;

&lt;p&gt;Schema in, dialect stated, definitions written down, plan attached, verification out. The model is the same; the inputs are what change the answer.&lt;/p&gt;




&lt;p&gt;&lt;em&gt;I packaged the prompts I use for this (32 of them: natural language → SQL with schema context, query review for NULLs, fan-out, N+1 and index use, EXPLAIN reading for PostgreSQL, MySQL and SQLite, schema and index reviews, zero-downtime migrations and rollbacks, ORM and injection checks, seed data and DB tests, window-function reports) plus a verification checklist and a PDF guide as the AI SQL &amp;amp; Database Prompt Pack: &lt;a href="https://payhip.com/b/VhqW7" rel="noopener noreferrer"&gt;https://payhip.com/b/VhqW7&lt;/a&gt;. Everything above works without it.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;— Pluto · &lt;a href="https://x.com/Mars_Peakul" rel="noopener noreferrer"&gt;@Mars_Peakul&lt;/a&gt;&lt;/em&gt;&lt;/p&gt;

</description>
      <category>sql</category>
      <category>ai</category>
      <category>database</category>
      <category>postgres</category>
    </item>
    <item>
      <title>Your AI-written README is probably lying: an evidence-first docs loop (with 2 free prompts)</title>
      <dc:creator>Pluto</dc:creator>
      <pubDate>Fri, 16 Oct 2026 13:06:45 +0000</pubDate>
      <link>https://dev.to/mars_peakul/your-ai-written-readme-is-probably-lying-an-evidence-first-docs-loop-with-2-free-prompts-3g6k</link>
      <guid>https://dev.to/mars_peakul/your-ai-written-readme-is-probably-lying-an-evidence-first-docs-loop-with-2-free-prompts-3g6k</guid>
      <description>&lt;p&gt;Ask Cursor, Claude Code or ChatGPT to “write a README for this repo,” and you’ll get something that looks exactly like a README: a features list, an installation section, a quickstart, usage examples, a contributing section, maybe a few badges. Then a new teammate runs the quickstart, and step two fails, because the script is called &lt;code&gt;dev&lt;/code&gt;, not &lt;code&gt;start&lt;/code&gt;, the &lt;code&gt;--verbose&lt;/code&gt; flag it documents never existed, and the &lt;code&gt;.env.example&lt;/code&gt; it tells them to copy isn’t in the repo.&lt;/p&gt;

&lt;p&gt;The model didn’t malfunction. It did what it was asked: produce a finished document. When it hit a gap, it filled it with what projects like yours &lt;em&gt;usually&lt;/em&gt; have. Fluent prose makes the guesses look exactly like the facts. Here’s the loop I use instead, and two full prompts you can paste today.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why “write docs for this” goes wrong
&lt;/h2&gt;

&lt;p&gt;The failure modes are predictable:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Convention filling.&lt;/strong&gt; &lt;code&gt;npm start&lt;/code&gt;, &lt;code&gt;--config&lt;/code&gt;, &lt;code&gt;DATABASE_URL&lt;/code&gt;, &lt;code&gt;LOG_LEVEL&lt;/code&gt;, a 404 on every endpoint. Each one is plausible, and any of them can be false for your code.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Invented rationale.&lt;/strong&gt; Ask for comments that explain &lt;em&gt;why&lt;/em&gt;, and you get reasons (“to avoid rate limiting”, “for performance”) that nobody ever gave. The next maintainer believes them.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Untested commands.&lt;/strong&gt; Setup and runbook steps nobody ran look identical to ones somebody did.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Confident numbers.&lt;/strong&gt; Defaults, limits, timeouts, supported versions. The most-copied parts of a doc are also the easiest to make up.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Write-once.&lt;/strong&gt; Even a perfect doc starts drifting at the next merge.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;None of this needs a smarter model. It needs a process where the model has to show its sources, and where “I don’t know” has somewhere to go.&lt;/p&gt;

&lt;h2&gt;
  
  
  The loop: evidence → outline → draft → verify → keep in sync
&lt;/h2&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;evidence → outline → draft → verify → keep in sync
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Evidence.&lt;/strong&gt; Before any prose: who is the reader, and what facts will the doc rely on, each with a source (file:line, commit, PR, note)? Whatever the evidence doesn’t cover becomes a question.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Outline.&lt;/strong&gt; Sections mapped to evidence rows. A section with no evidence is dropped or kept as a visible TODO stub. Cutting a section here costs nothing.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Draft.&lt;/strong&gt; Prose constrained by the outline. Commands copied from scripts, not “improved”. Unknowns written as &lt;code&gt;TODO: &amp;lt;question&amp;gt;&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Verify.&lt;/strong&gt; Run the copy-paste path on a clean machine. Grep every identifier. Check every number and every “because”.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Keep in sync.&lt;/strong&gt; Audit the docs against the code before each release, and after every incident for runbooks.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;If you only take one rule from this post: &lt;strong&gt;a visible TODO beats a plausible guess.&lt;/strong&gt; Tell the model that explicitly. Models are trained to be helpful, and “helpful” defaults to filling the gap. Saying that the gap is the helpful answer changes what you get back.&lt;/p&gt;

&lt;h2&gt;
  
  
  Free prompt 1: README from evidence, not from vibes
&lt;/h2&gt;

&lt;p&gt;Paste this with the repo &lt;code&gt;@&lt;/code&gt;-mentioned (Cursor), readable (Claude Code), or with the file tree, manifests and scripts pasted in (ChatGPT / Copilot Chat).&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;You are a senior engineer writing a README for this repository. You write only what the
code, config and files I give you can support. Anything you cannot support from evidence
becomes a visible TODO, not a guess.

## Context
- Repository / paths to read: {{REPO_PATHS}}
- What the project is for, in my words (may be incomplete): {{PROJECT_PURPOSE}}
- Who reads this README: {{AUDIENCE}}
- Commands I know work, or "unknown": {{KNOWN_COMMANDS}}

## Process (plan before writing)
1. Evidence scan. Read manifests, scripts (Makefile, package scripts, CI workflows),
   entrypoints, config and env var reads, LICENSE and existing docs. Record each fact
   you will rely on with its source file:line.
2. Gaps. List what a reader needs that the evidence does not tell you. Each gap becomes
   a TODO with a question for the maintainer.
3. Outline. Propose sections; for each, name the evidence rows it uses.
   STOP here and wait for my approval.
4. Draft. Quickstart in clean-clone order: prerequisites, install, configure, run, test.
   Copy commands exactly as defined in scripts.
5. Verification list. Every command, path, env var and flag in the README with its
   source, marked RAN (only if you executed it successfully) or UNVERIFIED.

## Output
### Evidence table   | # | Fact | Source (file:line) | Used in section |
### Gaps &amp;amp; TODOs
### Proposed outline
### README.md (after approval)
### Verification list | Item | Source | RAN / UNVERIFIED |

## Rules
- Never invent APIs, CLI flags, env vars, config keys, commands, defaults or behaviour
  not in the code. Mark unknowns as TODO: &amp;lt;question&amp;gt;.
- No badges, registries or CI services the repo doesn't configure.
- No "blazing fast" / "production-ready" without evidence.
- The license line must match the LICENSE file; if there is none, write TODO.
- Short and correct beats long and plausible.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Three parts do most of the work:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;The evidence table.&lt;/strong&gt; Every section has to point at rows. A Docker section with no Dockerfile has nothing to point at.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The stop after the outline.&lt;/strong&gt; You review ten lines of structure instead of three pages of prose.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;RAN / UNVERIFIED.&lt;/strong&gt; In a chat UI, everything is UNVERIFIED, and that’s honest. You run the quickstart; then you flip the labels.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Expect a few TODOs. A README written from incomplete material with &lt;em&gt;zero&lt;/em&gt; TODOs is the one to distrust.&lt;/p&gt;

&lt;h2&gt;
  
  
  Free prompt 2: the doc drift audit
&lt;/h2&gt;

&lt;p&gt;Docs were right once. Since then, a flag was renamed, a default changed, and a new required env var appeared. This prompt turns “the docs look mostly fine” into a ledger you can act on.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;You are a meticulous technical reviewer auditing documentation against the current code.
You treat every concrete statement in the docs as a claim to verify. The code is the
source of truth; you never change code to match the docs.

## Context
- Docs to audit: {{DOC_PATHS}}
- Code to verify against: {{CODE_PATHS}}
- What changed since the docs were last correct (git log / diff --stat, or "unknown"):
  {{CHANGE_SUMMARY}}
- Who reads these docs and what they do with them: {{READER}}

## Process
1. Extract every checkable claim and give it an ID: commands, CLI flags, env vars,
   config keys, defaults, endpoints, file paths, function names, versions, ports,
   limits, behaviour statements ("retries three times").
2. Verify each against the code:
   MATCH (cite line) / DRIFT (code says X, doc says Y; cite both) /
   MISSING-IN-CODE (list the search terms you used) /
   UNDOCUMENTED (user-facing things in code no doc mentions) /
   UNVERIFIABLE (say what would settle it).
3. Rank by reader harm: HIGH = copy-paste fails, data loss, security, wrong limits;
   MEDIUM = wrong for an edge case; LOW = wording. Add confidence per verdict.
4. Report and STOP. Do not edit anything.

## Output
### Summary (counts per verdict, top five HIGH-harm items)
### Claim ledger | ID | Doc location | Claim | Verdict | Evidence / search terms | Harm | Confidence |
### Undocumented user-facing changes
### Prevention (1–3 suggestions using tooling the repo already has)

## Rules
- Never invent APIs, flags, env vars or behaviour.
- If the doc describes behaviour the code lacks, report DRIFT and ask which is right.
- UNVERIFIABLE is an acceptable verdict. Don't upgrade it to MATCH.
- Mark anything you're unsure about as TODO: verify &amp;lt;question&amp;gt;.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Two details matter:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;It checks both directions.&lt;/strong&gt; Stale claims in the docs are half of drift. The other half is the new required env var nobody wrote down. That’s the UNDOCUMENTED section.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;“Code is the source of truth” is a rule, not a vibe.&lt;/strong&gt; Without it, an agent with write access may “helpfully” re-add a removed flag so the README is correct again.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Run it right before a release on the docs users touch first: the README quickstart, the install page, the config reference. Paste the release’s &lt;code&gt;git diff --stat&lt;/code&gt; as the change summary, so the model knows where drift is most likely.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why-comments: the rule that saves the next maintainer
&lt;/h2&gt;

&lt;p&gt;Comments that narrate code (&lt;code&gt;# loop over users&lt;/code&gt;) are noise. Comments that explain &lt;em&gt;why&lt;/em&gt; are gold, and also where models invent the most. The fix is a simple constraint:&lt;/p&gt;

&lt;blockquote&gt;
&lt;p&gt;A why-comment must come from the code itself, a ticket, a commit message or a person. Otherwise write &lt;code&gt;TODO(why): &amp;lt;question&amp;gt;&lt;/code&gt;.&lt;/p&gt;
&lt;/blockquote&gt;

&lt;p&gt;Then read the list of TODO(why) questions the model produces. It’s often the most valuable output of the session: a list of exactly the knowledge that disappears when someone leaves. Paste it into the PR and let the author answer.&lt;/p&gt;

&lt;h2&gt;
  
  
  The 10-minute hallucination check
&lt;/h2&gt;

&lt;p&gt;Before you merge any AI-written doc:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Pull out every command, flag, env var, config key, endpoint and file path.&lt;/li&gt;
&lt;li&gt;Search each one in the repo (&lt;code&gt;git grep -n "&amp;lt;identifier&amp;gt;"&lt;/code&gt;). Anything not found is guilty until proven innocent.&lt;/li&gt;
&lt;li&gt;Run the copy-paste path on a clean environment, in order.&lt;/li&gt;
&lt;li&gt;Every number (default, limit, port, version) needs a source line.&lt;/li&gt;
&lt;li&gt;Every “because” needs a source. No source, no because.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;And don’t let AI write these alone: security or compliance statements, SLAs, license text, incident disclosures, or destructive-operation steps. A human owns every sentence there.&lt;/p&gt;

&lt;h2&gt;
  
  
  The shape that works
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Part&lt;/th&gt;
&lt;th&gt;Purpose&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Role&lt;/td&gt;
&lt;td&gt;“Senior engineer writing… from evidence”, “scribe”, “auditor”&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Inputs&lt;/td&gt;
&lt;td&gt;Paths, the reader, real source material (code, PR bodies, notes)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Process&lt;/td&gt;
&lt;td&gt;Evidence and outline before prose&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Output contract&lt;/td&gt;
&lt;td&gt;Tables with Source and RAN / UNVERIFIED columns&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Rules&lt;/td&gt;
&lt;td&gt;Never invent; TODO unknowns; doc-only; code is the source of truth&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;A column titled “Source (file:line)” has to be filled per row, and an empty cell is visible in a way a confident paragraph never is. That’s the whole trick.&lt;/p&gt;

&lt;p&gt;Try it on a doc you know well: regenerate your own README with prompt 1 from the code alone, or run prompt 2 against it, and check every claim and every TODO it raises.&lt;/p&gt;




&lt;p&gt;&lt;em&gt;I packaged the eight documentation prompts I use (README from a codebase, why-comments &amp;amp; docstrings, API reference / OpenAPI, ADRs, changelog &amp;amp; release notes, onboarding guide, runbooks, doc drift audit) plus two checklists, a Cursor rule and a PDF guide, as the AI Documentation Prompt Pack: &lt;a href="https://payhip.com/b/a8p1N" rel="noopener noreferrer"&gt;https://payhip.com/b/a8p1N&lt;/a&gt;. Everything above works without it.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;— Pluto · &lt;a href="https://x.com/Mars_Peakul" rel="noopener noreferrer"&gt;@Mars_Peakul&lt;/a&gt;&lt;/em&gt;&lt;/p&gt;

</description>
      <category>ai</category>
      <category>documentation</category>
      <category>productivity</category>
      <category>programming</category>
    </item>
    <item>
      <title>Stop asking AI to “clean this up”: a safe refactoring loop (with 2 free prompts)</title>
      <dc:creator>Pluto</dc:creator>
      <pubDate>Thu, 15 Oct 2026 06:46:28 +0000</pubDate>
      <link>https://dev.to/mars_peakul/stop-asking-ai-to-clean-this-up-a-safe-refactoring-loop-with-2-free-prompts-32e6</link>
      <guid>https://dev.to/mars_peakul/stop-asking-ai-to-clean-this-up-a-safe-refactoring-loop-with-2-free-prompts-32e6</guid>
      <description>&lt;p&gt;Ask Cursor, Claude Code or ChatGPT to “clean this up” or “refactor this,” and you’ll usually get &lt;em&gt;something&lt;/em&gt;: new folders, renamed symbols, a fashionable pattern, maybe a dependency bump. Sometimes it’s even an improvement.&lt;/p&gt;

&lt;p&gt;Often it’s an unreviewable rewrite. The diff mixes structure with silent behaviour changes. Tests go green because they now assert the new world, not because yesterday’s behaviour was locked. Reviewers approve the vibe and miss the logic edit in the noise.&lt;/p&gt;

&lt;p&gt;AI isn’t bad at refactoring. “Clean this up” just skips every step that makes structural change safe and asks for a finished architecture in one shot. Here’s a loop I use instead — and two full prompts you can paste today.&lt;/p&gt;

&lt;h2&gt;
  
  
  The loop: map → safety net → small slice → prove → describe
&lt;/h2&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;map → safety net → small slice → prove → describe
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Map&lt;/strong&gt; — inventory concrete smells with locations; pick one PR-sized first slice; write what’s out of scope.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Safety net&lt;/strong&gt; — characterization (or existing) tests that pin &lt;em&gt;today’s&lt;/em&gt; behaviour &lt;em&gt;before&lt;/em&gt; you move code.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Small slice&lt;/strong&gt; — one extract, one responsibility split, one rename batch — not a redesign.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Prove&lt;/strong&gt; — same tests green after; public contracts unchanged unless this PR is explicitly a migration.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Describe&lt;/strong&gt; — PR text that states the behaviour contract, reading order, and residual risk.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;If you only remember one rule: &lt;strong&gt;don’t let the model edit production code until something green locks the behaviour you’re about to move.&lt;/strong&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  Free prompt 1: smell map before any edit
&lt;/h2&gt;

&lt;p&gt;Paste this when you’re staring at a messy module and tempted to say “rewrite it.”&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;You are a senior engineer planning a safe refactor. Do not change any code yet.

## Context
- Paths in scope: {{TARGET_PATHS}}
- Goal (one sentence): {{GOALS}}
- Hard constraints (API freeze, no new deps, deadline): {{CONSTRAINTS}}
- Time / PR budget for the first pass: {{TIME_BUDGET}}
- What I know about tests here: {{TEST_COVERAGE_NOTES}}

## Process
1. Inventory concrete smells with file:line or a short quote. Cover different
   categories (long function, duplication, mixed responsibilities, dead code,
   leaky abstraction, hidden side effects). Cap at 12.
2. Score each: payoff (H/M/L), risk (H/M/L), test safety (none/thin/adequate),
   size (S/M/L).
3. Rank by (payoff ÷ risk), then size. Prefer high-payoff / low-risk / S first.
4. Propose ONE first slice: done-when, smells included, safety net required
   before edits, explicit out-of-scope, suggested PR title.
5. Stop. No edits. No rewrite proposal.

## Output
### Smell inventory (table)
### Ranking
### First slice
### Open questions (max 5)

## Rules
- Every smell needs a location. "This is messy" is not a smell.
- Do not invent coverage % or hours saved. Unknown → say unknown, raise risk.
- Prefer surgery over rewrite.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Two details matter. &lt;strong&gt;Locations&lt;/strong&gt; stop vibes-based cleanup. &lt;strong&gt;Out of scope&lt;/strong&gt; on the first slice stops the model from boiling the ocean in the same breath as the plan.&lt;/p&gt;

&lt;h2&gt;
  
  
  Free prompt 2: characterization before the extract
&lt;/h2&gt;

&lt;p&gt;Once you’ve picked a slice, pin behaviour &lt;em&gt;before&lt;/em&gt; moving code:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;You are building a characterization safety net before a refactor.
Do not change production code.

## Context
- Code under edit: {{TARGET_CODE}}
- Behaviours that must stay the same: {{PUBLIC_BEHAVIOURS}}
- Known quirks / edge cases: {{KNOWN_EDGE_CASES}}
- Existing tests: {{EXISTING_TESTS}}
- Test command: {{TEST_COMMAND}}

## Process
1. List observable contracts (returns, errors, side effects, ordering).
   Mark each MUST-PRESERVE or ALLOWED-TO-IMPROVE.
2. Gap-analyze against existing tests.
3. Add the smallest tests that pin current behaviour — including quirks.
   If something looks like a bug, still characterize it and label the test
   CHARACTERIZATION. Do not "fix" it in this step.
4. Run {{TEST_COMMAND}} on the CURRENT code. All new tests must pass before
   any structural edit.

## Rules
- No production edits.
- Do not weaken or delete existing assertions.
- Prefer outputs/side effects over mock call-order tests.
- If you can't run tests here, label them UNVERIFIED and give exact commands.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Characterization is deliberately boring. That’s the point. You’re buying a tripwire for the extract you’re about to do.&lt;/p&gt;

&lt;h2&gt;
  
  
  Then make the slice boring too
&lt;/h2&gt;

&lt;p&gt;When you finally extract or split:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Quote the exact chunk, its inputs/outputs/side effects, then move it in steps: add new function → switch caller → delete old body.&lt;/li&gt;
&lt;li&gt;Ban drive-by churn in writing: no whole-file reformat, no unrelated renames, no dependency bumps in the same PR.&lt;/li&gt;
&lt;li&gt;Keep public signatures stable unless this PR &lt;em&gt;is&lt;/em&gt; the migration (then use expand/contract: new alongside old → migrate callers in batches → remove old).&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;A useful interrupt when the agent starts redesigning:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;List every file change not required by the approved slice. Revert those.
Did any user-visible behaviour, wire format, error code or log field change?
Yes/No per item. If Yes, split it out of this refactor PR.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Renames: expand/contract, not flag day
&lt;/h2&gt;

&lt;p&gt;Repo-wide renames are where AI is both strongest and most dangerous. A single replace-all feels productive and produces a diff nobody can review — and it misses the dynamic call site in another package, the config key, or the old mobile client.&lt;/p&gt;

&lt;p&gt;Prefer &lt;strong&gt;expand/contract&lt;/strong&gt;:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Introduce the new name alongside the old (shim if you need a public export).&lt;/li&gt;
&lt;li&gt;Migrate callers in &lt;strong&gt;directory-sized batches&lt;/strong&gt;, each leaving CI green.&lt;/li&gt;
&lt;li&gt;Update docs and generated clients.&lt;/li&gt;
&lt;li&gt;Remove the old name only when inventory search returns zero.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;Ask the model for an inventory table first (definition / internal / public / tests / config / generated), then execute &lt;strong&gt;step one only&lt;/strong&gt; in that session. Paste remaining counts into the next session. That handoff beats one mega-chat that “just finishes it.”&lt;/p&gt;

&lt;h2&gt;
  
  
  A miniature walkthrough (illustrative)
&lt;/h2&gt;

&lt;p&gt;&lt;em&gt;Fictional and simplified — no real metrics.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;You have a 1,200-line &lt;code&gt;PricingService&lt;/code&gt; that mixes list price, discounts, tax, FX and invoice formatting. Constraint: keep &lt;code&gt;price(cart)&lt;/code&gt; for one release.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Map:&lt;/strong&gt; extract tax ranks high payoff / medium risk; deleting a commented &lt;code&gt;legacyCouponPath&lt;/code&gt; is tempting but secondary.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Net:&lt;/strong&gt; two characterization tests lock half-unit rounding and “unknown country” errors on current code.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Slice:&lt;/strong&gt; new &lt;code&gt;TaxCalculator&lt;/code&gt;; &lt;code&gt;price&lt;/code&gt; delegates; signature unchanged; suite still green.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Describe:&lt;/strong&gt; PR reading order = characterization tests → new type → delegating methods → unchanged exports. Dead-code delete waits for a later HIGH-confidence pass.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Nothing magical happened. The prompts kept the first change small enough that a human could still own the merge.&lt;/p&gt;

&lt;h2&gt;
  
  
  Know when not to start
&lt;/h2&gt;

&lt;p&gt;Skip AI-led cleanup when you can’t state the goal in one sentence, when there’s no time for a safety net, during a freeze/incident, or when the real need is a bug fix smuggled as “refactor.” Stop mid-session when the diff grows past the slice, when tests are “fixed” by deleting assertions, or when you couldn’t explain the change yourself.&lt;/p&gt;

&lt;p&gt;Also park the work when you don’t own the module and can’t get a reviewer who does, or when the model’s first suggestion is a rewrite. Return to the smell map and pick a leaf extraction instead.&lt;/p&gt;

&lt;h2&gt;
  
  
  The shape that works
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Part&lt;/th&gt;
&lt;th&gt;Purpose&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Role&lt;/td&gt;
&lt;td&gt;“Senior engineer planning/performing a safe refactor…”&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Inputs&lt;/td&gt;
&lt;td&gt;Paths, goal, constraints, real test command&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Process&lt;/td&gt;
&lt;td&gt;Map → net → slice; plan before wide edits&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Output contract&lt;/td&gt;
&lt;td&gt;Tables for smells, confidence grades, reading order&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Rules&lt;/td&gt;
&lt;td&gt;No drive-bys, no fake metrics, no test vandalism&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Try it on a cleanup you already finished: give the model only the original messy files and constraints, run the smell-map prompt, and see whether the first slice is something you’d still approve — with a safety net called out before edits.&lt;/p&gt;




&lt;p&gt;&lt;em&gt;I packaged the eight refactoring prompts I use (smell map, characterization net, extract, god-class split, rename/migration, dead-code cleanup, strangler-fig, PR guide) plus two checklists, a Cursor rule and a PDF guide, as the **AI Refactoring Prompt Pack&lt;/em&gt;&lt;em&gt;: &lt;a href="https://lirenplr.gumroad.com/l/ypcsuc" rel="noopener noreferrer"&gt;https://lirenplr.gumroad.com/l/ypcsuc&lt;/a&gt;. Everything above works without it.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;— Pluto · &lt;a href="https://x.com/Mars_Peakul" rel="noopener noreferrer"&gt;@Mars_Peakul&lt;/a&gt;&lt;/em&gt;&lt;/p&gt;

</description>
      <category>ai</category>
      <category>refactoring</category>
      <category>productivity</category>
      <category>programming</category>
    </item>
    <item>
      <title>Stop asking AI to “write tests for this” — 5 prompt changes that make generated tests catch bugs</title>
      <dc:creator>Pluto</dc:creator>
      <pubDate>Wed, 14 Oct 2026 02:40:01 +0000</pubDate>
      <link>https://dev.to/mars_peakul/stop-asking-ai-to-write-tests-for-this-5-prompt-changes-that-make-generated-tests-catch-bugs-3n2n</link>
      <guid>https://dev.to/mars_peakul/stop-asking-ai-to-write-tests-for-this-5-prompt-changes-that-make-generated-tests-catch-bugs-3n2n</guid>
      <description>&lt;p&gt;AI coding tools can write a test file in seconds. Most developers have also noticed the catch: the tests are green, coverage goes up, and a real bug ships straight through them.&lt;/p&gt;

&lt;p&gt;That usually isn’t the model being bad at testing. It’s the prompt leaving out everything that makes a test valuable. Here are five changes I now make to every testing prompt — in Cursor, Claude Code, ChatGPT or Copilot Chat — and why each one matters.&lt;/p&gt;

&lt;h2&gt;
  
  
  1. Give it the intent, not just the code
&lt;/h2&gt;

&lt;p&gt;If the only input is the implementation, the implementation becomes the spec. The model reads what the code &lt;em&gt;does&lt;/em&gt; and asserts exactly that — including any bug.&lt;/p&gt;

&lt;p&gt;Add one or two sentences of intent, in your own words:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;What this code is supposed to do:
prorate() returns the charge for the unused part of a billing period,
rounded half-up to cents. It never returns a negative amount.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Now the model has something to test &lt;em&gt;against&lt;/em&gt;. If it notices the code can return a negative amount, it has a reason to flag it instead of pinning it.&lt;/p&gt;

&lt;h2&gt;
  
  
  2. Ask for a plan before any code
&lt;/h2&gt;

&lt;p&gt;“Write tests” invites volume. Ask for a behaviour inventory and a case table first:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Before writing any code:
1. List every observable behaviour (return values, errors, side effects, branches).
   Mark anything that looks like a bug with [SUSPECT].
2. For each behaviour, list cases: happy path, boundaries (empty, zero, one, max,
   off-by-one), invalid input, error paths.
Show me both. Then write the tests.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A case table takes ten seconds to review. If the boundaries or error paths are missing, you see it immediately — instead of discovering it in 300 lines of generated code.&lt;/p&gt;

&lt;h2&gt;
  
  
  3. Attach one existing test file
&lt;/h2&gt;

&lt;p&gt;Describing your conventions (“we use Vitest, factories live in &lt;code&gt;tests/factories&lt;/code&gt;, we name tests like…”) works poorly. Showing them works well:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Conventions to copy: tests/billing/invoice.test.ts
Match its imports, helpers, file location and naming.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This one line stops most of the “new assertion library, different folder, duplicate fixtures” problems.&lt;/p&gt;

&lt;h2&gt;
  
  
  4. Write the rules the model would otherwise break
&lt;/h2&gt;

&lt;p&gt;Models take the shortest path to green. State the boundaries explicitly:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;Rules:
- Do not change production code to make tests pass. If the code seems wrong, report it.
- Expected values must be hand-computed literals, not the same formula as the code.
- Only stub true boundaries: clock, randomness, network, third-party APIs.
- No fixed sleeps. Freeze time and seed randomness explicitly.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The second rule alone removes a whole class of “mirror tests” — tests that agree with the implementation by construction and can never fail for the reason you care about.&lt;/p&gt;

&lt;h2&gt;
  
  
  5. Make it justify every test
&lt;/h2&gt;

&lt;p&gt;End with a self-check:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;For each test, state in one line the specific bug it would catch.
Delete any test whose answer is "none" or "same as another test".
List behaviours from the case table that still have no test.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Then do the human version: break the code on purpose (flip a &lt;code&gt;&amp;lt;&lt;/code&gt; to &lt;code&gt;&amp;lt;=&lt;/code&gt;, return early) and see whether anything goes red. If nothing does, the tests are decoration.&lt;/p&gt;

&lt;h2&gt;
  
  
  Different jobs need different prompts
&lt;/h2&gt;

&lt;p&gt;The five changes above are the skeleton. The &lt;em&gt;process&lt;/em&gt; section should change with the job:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Integration/API tests:&lt;/strong&gt; rank scenarios by risk — contract, validation, auth (including another tenant’s resource), persistence, idempotency, downstream failure — and forbid mocking the database.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;E2E:&lt;/strong&gt; separate checkpoints worth asserting from incidental UI, use role/label locators, and ask for an explicit flake review.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Legacy code:&lt;/strong&gt; write &lt;em&gt;characterization&lt;/em&gt; tests that pin current behaviour, bugs included, before you change anything.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Flaky tests:&lt;/strong&gt; ask for ranked hypotheses with evidence and a reproduction step. Retries and longer sleeps are not fixes.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Coverage:&lt;/strong&gt; treat the percentage as one input to a risk-based plan, not the goal.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  The shape that works
&lt;/h2&gt;

&lt;p&gt;Every good testing prompt I use has the same five parts:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Part&lt;/th&gt;
&lt;th&gt;Purpose&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Role&lt;/td&gt;
&lt;td&gt;“Senior engineer writing tests a skeptical reviewer will accept”&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Context&lt;/td&gt;
&lt;td&gt;Target, intent/spec, framework, one example test, what not to touch&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Process&lt;/td&gt;
&lt;td&gt;Numbered steps, plan before code&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Output contract&lt;/td&gt;
&lt;td&gt;Exact sections and tables to return&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Rules&lt;/td&gt;
&lt;td&gt;The shortcuts the model must not take&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Try it on a function you know well. If the case table finds an edge case you hadn’t written down, it’s working.&lt;/p&gt;




&lt;p&gt;&lt;em&gt;I packaged the eight prompts I use for this — unit, spec-first, integration/API, E2E, characterization, flaky diagnosis, coverage planning and mock boundaries — plus two checklists, a Cursor rule and a PDF guide, as the **AI Test Generation Prompt Pack&lt;/em&gt;&lt;em&gt;: &lt;a href="https://lirenplr.gumroad.com/l/cuofwr" rel="noopener noreferrer"&gt;https://lirenplr.gumroad.com/l/cuofwr&lt;/a&gt;. Everything above works without it.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;— Pluto · &lt;a href="https://x.com/Mars_Peakul" rel="noopener noreferrer"&gt;@Mars_Peakul&lt;/a&gt;&lt;/em&gt;&lt;/p&gt;

</description>
      <category>testing</category>
      <category>ai</category>
      <category>productivity</category>
      <category>programming</category>
    </item>
    <item>
      <title>Stop asking AI to "review this PR" — use a risk map instead</title>
      <dc:creator>Pluto</dc:creator>
      <pubDate>Tue, 13 Oct 2026 14:03:00 +0000</pubDate>
      <link>https://dev.to/mars_peakul/stop-asking-ai-to-review-this-pr-use-a-risk-map-instead-26kl</link>
      <guid>https://dev.to/mars_peakul/stop-asking-ai-to-review-this-pr-use-a-risk-map-instead-26kl</guid>
      <description>&lt;p&gt;If you paste a pull request into ChatGPT, Claude, Cursor, or Copilot Chat and say “review this,” you usually get:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;a summary of what the diff already shows&lt;/li&gt;
&lt;li&gt;a handful of style opinions&lt;/li&gt;
&lt;li&gt;a generic reminder about “validating inputs”&lt;/li&gt;
&lt;li&gt;a friendly “looks good overall”&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;That is not a review. That is a book report.&lt;/p&gt;

&lt;p&gt;After enough of those, people either stop using AI for review or — worse — start treating the essay as approval.&lt;/p&gt;

&lt;h2&gt;
  
  
  What actually goes wrong
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;No intent.&lt;/strong&gt; Without one sentence on &lt;em&gt;why&lt;/em&gt; the change exists, the model cannot tell a deliberate behaviour change from a bug.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;No priority.&lt;/strong&gt; Naming nits compete with authz bugs for the same paragraph budget.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;No output contract.&lt;/strong&gt; Free-form prose hides severity. You want &lt;strong&gt;Must fix&lt;/strong&gt; / &lt;strong&gt;Should fix&lt;/strong&gt; / &lt;strong&gt;Nit&lt;/strong&gt;, locations, and a verdict.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Equal time for unequal risk.&lt;/strong&gt; Renames and payment-path changes should not get the same depth.&lt;/p&gt;

&lt;h2&gt;
  
  
  A better default loop
&lt;/h2&gt;

&lt;p&gt;Use four steps:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Diff + intent&lt;/strong&gt; — skim &lt;code&gt;--stat&lt;/code&gt;, write one sentence of purpose.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Risk map&lt;/strong&gt; — ask the model &lt;em&gt;only&lt;/em&gt; which areas deserve depth (auth, money, migrations, public API, supply chain, hot paths).&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Deep dives&lt;/strong&gt; — new prompts (or new turns) on those areas: security, tests, API breaks, migrations, etc.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Human verdict&lt;/strong&gt; — dedupe, drop wrong nits, you own merge.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;The important part is splitting &lt;strong&gt;map&lt;/strong&gt; from &lt;strong&gt;deep dive&lt;/strong&gt;. One mega-prompt on a 3k-line PR burns context and produces shallow commentary.&lt;/p&gt;

&lt;h2&gt;
  
  
  A skeleton that works across tools
&lt;/h2&gt;

&lt;p&gt;You can adapt this in Cursor, Claude Code, ChatGPT, or Copilot Chat:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;You are a senior engineer doing a pre-merge review. Do not edit files.

## Context
- Intent: &amp;lt;one sentence&amp;gt;
- Diffstat: &amp;lt;paste&amp;gt;
- Risk notes: &amp;lt;auth? migration? public API?&amp;gt;

## Process
1. Risk map (area → why → files)
2. Correctness vs intent
3. Security (authz, injection, secrets)
4. Tests (new behaviour covered? tests weakened?)
5. Only then maintainability that hides real risk

## Output
### Risk map
### Findings (Must fix / Should fix / Nit, with path:line, why, fix)
### Verdict: Approve | Approve with nits | Request changes
### Open questions

Do not invent issues. If nothing serious, say so.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Keep the output contract. It is doing more work than the adjectives in the role line.&lt;/p&gt;

&lt;h2&gt;
  
  
  Specialist passes beat one giant checklist
&lt;/h2&gt;

&lt;p&gt;Once you have a risk map, fan out:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Trust boundary → security threat model + Pass/Fail evidence&lt;/li&gt;
&lt;li&gt;Behaviour change → behaviour↔test matrix (watch for deleted or loosened tests)&lt;/li&gt;
&lt;li&gt;Schema → expand/contract and lock risk&lt;/li&gt;
&lt;li&gt;Manifest/lockfile → necessity and install scripts, not only &lt;code&gt;audit&lt;/code&gt; noise&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;You rarely need every pass. Two deep dives on the real risks beat eight shallow ones.&lt;/p&gt;

&lt;h2&gt;
  
  
  Team norms that keep this healthy
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Human owns merge.&lt;/strong&gt; The model is a junior reviewer, not a gate bot.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Shared severity words.&lt;/strong&gt; Must fix means blocks merge.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Read-only review chats.&lt;/strong&gt; Implement fixes in a separate turn so “findings” do not silently become a rewrite.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Authors can paste a risk map into the PR&lt;/strong&gt; to save reviewers’ discovery time — without requiring them to accept every nit.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Privacy reminder
&lt;/h2&gt;

&lt;p&gt;If your company forbids pasting code into a given tool, these prompts do not override that. Use whatever surface policy allows (including self-hosted options).&lt;/p&gt;

&lt;h2&gt;
  
  
  Soft close
&lt;/h2&gt;

&lt;p&gt;I’ve been packaging this loop as a small set of copy-paste prompts and checklists (full PR, security, performance, tests, API, migrations, frontend a11y, dependencies) for people who already live in AI coding tools and just want reviews that surface real risk.&lt;/p&gt;

&lt;p&gt;If you try the risk-map-first skeleton above on your next non-trivial PR, watch whether the Must-fix list gets shorter and more serious. That feedback loop matters more than any tool brand.&lt;/p&gt;

&lt;p&gt;— Pluto · &lt;a href="https://x.com/Mars_Peakul" rel="noopener noreferrer"&gt;@Mars_Peakul&lt;/a&gt;&lt;/p&gt;

</description>
      <category>ai</category>
      <category>codequality</category>
      <category>productivity</category>
      <category>webdev</category>
    </item>
    <item>
      <title>One AGENTS.md to rule Claude Code, Cursor and Codex</title>
      <dc:creator>Pluto</dc:creator>
      <pubDate>Tue, 13 Oct 2026 06:48:38 +0000</pubDate>
      <link>https://dev.to/mars_peakul/one-agentsmd-to-rule-claude-code-cursor-and-codex-3jmi</link>
      <guid>https://dev.to/mars_peakul/one-agentsmd-to-rule-claude-code-cursor-and-codex-3jmi</guid>
      <description>&lt;p&gt;If you use more than one AI coding agent, you've probably ended up with three instruction files: a &lt;code&gt;CLAUDE.md&lt;/code&gt; for Claude Code, a pile of &lt;code&gt;.cursor/rules&lt;/code&gt; for Cursor, and an &lt;code&gt;AGENTS.md&lt;/code&gt; for Codex. They start out identical. A month later one still says &lt;code&gt;npm&lt;/code&gt;, another says &lt;code&gt;pnpm&lt;/code&gt;, and the third forgot that tests live next to the code.&lt;/p&gt;

&lt;p&gt;That's how instruction files drift apart. The fix is simple: &lt;strong&gt;make &lt;code&gt;AGENTS.md&lt;/code&gt; the single source of truth and keep every tool-specific file thin.&lt;/strong&gt; This post shows the layout, how each tool actually picks up &lt;code&gt;AGENTS.md&lt;/code&gt;, and a template you can copy.&lt;/p&gt;

&lt;h2&gt;
  
  
  The layout
&lt;/h2&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;your-repo/
├── AGENTS.md            # canonical: commands, layout, conventions, definition of done
├── CLAUDE.md            # "@AGENTS.md" + Claude-only notes
├── .claude/
│   ├── settings.json    # permissions + hooks
│   ├── agents/          # subagents
│   └── skills/          # procedures that load on demand
├── .cursor/
│   ├── rules/           # .mdc rules, with the core rule pointing at AGENTS.md
│   └── cli.json         # permissions for the `agent` CLI
├── .cursorignore
└── .codex/
    ├── config.toml      # sandbox + approval defaults
    └── agents/          # custom agents
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;AGENTS.md&lt;/code&gt; holds everything every agent needs. The other files hold only what is specific to one tool: its behaviour, permissions and features.&lt;/p&gt;

&lt;h2&gt;
  
  
  How each tool picks up AGENTS.md
&lt;/h2&gt;

&lt;p&gt;This is the part people get wrong, because the three tools load it differently.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Codex&lt;/strong&gt; builds an instruction chain once per run. It starts with the global file (&lt;code&gt;~/.codex/AGENTS.override.md&lt;/code&gt; or &lt;code&gt;AGENTS.md&lt;/code&gt;), then walks every directory from the project root down to your working directory. In each one it checks &lt;code&gt;AGENTS.override.md&lt;/code&gt;, then &lt;code&gt;AGENTS.md&lt;/code&gt;, then any &lt;code&gt;project_doc_fallback_filenames&lt;/code&gt;, and takes at most one file per directory. Files closer to your working directory come later, so they win when instructions conflict. The combined chain has a default size cap of 32 KiB, and Codex stops adding files once it reaches it.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Cursor&lt;/strong&gt; supports &lt;code&gt;AGENTS.md&lt;/code&gt; in the root and in subdirectories. Nested files combine with their parents, and the more specific instructions take precedence.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Claude Code&lt;/strong&gt; has the catch. It reads &lt;code&gt;AGENTS.md&lt;/code&gt; directly &lt;strong&gt;only when there's no &lt;code&gt;CLAUDE.md&lt;/code&gt; or &lt;code&gt;CLAUDE.local.md&lt;/code&gt;&lt;/strong&gt; in the working directory or above. Once you add a &lt;code&gt;CLAUDE.md&lt;/code&gt;, put an import at the top so both load:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight markdown"&gt;&lt;code&gt;&lt;span class="gh"&gt;# CLAUDE.md&lt;/span&gt;
@AGENTS.md
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A personal, uncommitted &lt;code&gt;CLAUDE.local.md&lt;/code&gt; also counts as "a CLAUDE.md exists". So even if you never create a project &lt;code&gt;CLAUDE.md&lt;/code&gt;, adding a local one silently stops Claude reading &lt;code&gt;AGENTS.md&lt;/code&gt;. Keep the explicit &lt;code&gt;@AGENTS.md&lt;/code&gt; import and that can't happen.&lt;/p&gt;

&lt;h2&gt;
  
  
  The canonical AGENTS.md
&lt;/h2&gt;

&lt;p&gt;Here's a trimmed version of the template I use. Replace the placeholders with your own stack.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight markdown"&gt;&lt;code&gt;&lt;span class="gh"&gt;# AGENTS.md&lt;/span&gt;

&lt;span class="gu"&gt;## Project snapshot&lt;/span&gt;
&lt;span class="p"&gt;-&lt;/span&gt; What it is: &lt;span class="nt"&gt;&amp;lt;one&lt;/span&gt; &lt;span class="na"&gt;sentence&lt;/span&gt;&lt;span class="nt"&gt;&amp;gt;&lt;/span&gt;
&lt;span class="p"&gt;-&lt;/span&gt; Main language / runtime: &lt;span class="nt"&gt;&amp;lt;TypeScript&lt;/span&gt; &lt;span class="err"&gt;5,&lt;/span&gt; &lt;span class="na"&gt;Node&lt;/span&gt; &lt;span class="err"&gt;22&lt;/span&gt;&lt;span class="nt"&gt;&amp;gt;&lt;/span&gt;
&lt;span class="p"&gt;-&lt;/span&gt; Package manager: &lt;span class="nt"&gt;&amp;lt;pnpm&amp;gt;&lt;/span&gt;. Do not use any other package manager.
&lt;span class="p"&gt;-&lt;/span&gt; Layout:
&lt;span class="p"&gt;  -&lt;/span&gt; &lt;span class="sb"&gt;`apps/web/`&lt;/span&gt;: frontend
&lt;span class="p"&gt;  -&lt;/span&gt; &lt;span class="sb"&gt;`apps/api/`&lt;/span&gt;: HTTP API (handlers in &lt;span class="sb"&gt;`apps/api/src/handlers/`&lt;/span&gt;)
&lt;span class="p"&gt;  -&lt;/span&gt; &lt;span class="sb"&gt;`packages/db/`&lt;/span&gt;: schema + migrations

&lt;span class="gu"&gt;## Commands&lt;/span&gt;
&lt;span class="p"&gt;-&lt;/span&gt; Install: &lt;span class="sb"&gt;`&amp;lt;pnpm install&amp;gt;`&lt;/span&gt;
&lt;span class="p"&gt;-&lt;/span&gt; Unit tests (fast, run often): &lt;span class="sb"&gt;`&amp;lt;pnpm test&amp;gt;`&lt;/span&gt;
&lt;span class="p"&gt;-&lt;/span&gt; Single test file: &lt;span class="sb"&gt;`&amp;lt;pnpm test -- path/to/file.test.ts&amp;gt;`&lt;/span&gt;
&lt;span class="p"&gt;-&lt;/span&gt; Lint + types: &lt;span class="sb"&gt;`&amp;lt;pnpm lint &amp;amp;&amp;amp; pnpm typecheck&amp;gt;`&lt;/span&gt;
&lt;span class="p"&gt;-&lt;/span&gt; Build: &lt;span class="sb"&gt;`&amp;lt;pnpm build&amp;gt;`&lt;/span&gt;

&lt;span class="gu"&gt;## Conventions&lt;/span&gt;
&lt;span class="p"&gt;-&lt;/span&gt; Named exports, no default exports.
&lt;span class="p"&gt;-&lt;/span&gt; Errors: return &lt;span class="sb"&gt;`{ code, message }`&lt;/span&gt; objects from services; never throw raw strings.
&lt;span class="p"&gt;-&lt;/span&gt; New code needs tests next to it (&lt;span class="sb"&gt;`*.test.ts`&lt;/span&gt;).

&lt;span class="gu"&gt;## Working agreement&lt;/span&gt;
&lt;span class="p"&gt;1.&lt;/span&gt; Restate the task in one or two lines and list the files you expect to touch before editing.
&lt;span class="p"&gt;2.&lt;/span&gt; Make the smallest change that solves the task. No drive-by refactors.
&lt;span class="p"&gt;3.&lt;/span&gt; If requirements are ambiguous, stop and ask. Do not guess on behaviour.
&lt;span class="p"&gt;4.&lt;/span&gt; Never commit secrets, tokens, or &lt;span class="sb"&gt;`.env*`&lt;/span&gt; files.
&lt;span class="p"&gt;5.&lt;/span&gt; Do not run &lt;span class="sb"&gt;`git push`&lt;/span&gt;, &lt;span class="sb"&gt;`git reset --hard`&lt;/span&gt;, &lt;span class="sb"&gt;`git clean -fd`&lt;/span&gt;, force-pushes,
   or destructive DB commands unless explicitly asked.

&lt;span class="gu"&gt;## Definition of done&lt;/span&gt;
&lt;span class="p"&gt;-&lt;/span&gt; [ ] Lint + types pass
&lt;span class="p"&gt;-&lt;/span&gt; [ ] Tests pass (and a new test covers the change)
&lt;span class="p"&gt;-&lt;/span&gt; [ ] Diff is limited to files related to the task
&lt;span class="p"&gt;-&lt;/span&gt; [ ] Short summary: what changed, why, how it was verified, open risks

&lt;span class="gu"&gt;## Code Review Rules&lt;/span&gt;
&lt;span class="p"&gt;-&lt;/span&gt; Flag any handler that reads request input without validation.
&lt;span class="p"&gt;-&lt;/span&gt; Flag SQL built with string concatenation.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  Why it's built this way
&lt;/h3&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Commands come first&lt;/strong&gt; because wrong commands cause most wasted agent turns: &lt;code&gt;npm&lt;/code&gt; instead of &lt;code&gt;pnpm&lt;/code&gt;, or the wrong test runner. The single-file test command also saves tokens, since the agent stops running the whole suite on every iteration.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The working agreement&lt;/strong&gt; turns common failure modes, like silent scope creep and guessing, into explicit rules.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The definition of done&lt;/strong&gt; gives every agent the same exit criteria. Without it you get "Done!" while the tests still fail.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;## Code Review Rules&lt;/code&gt;&lt;/strong&gt; is a heading Codex's GitHub code review looks for, so the review guidance comes along for free.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Keep it short. Leave formatting checks to CI, not the rule file. And write instructions the agent can verify: "Run &lt;code&gt;pnpm test&lt;/code&gt; before finishing" works better than "test your changes".&lt;/p&gt;

&lt;h2&gt;
  
  
  The thin files
&lt;/h2&gt;

&lt;h3&gt;
  
  
  CLAUDE.md
&lt;/h3&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight markdown"&gt;&lt;code&gt;&lt;span class="gh"&gt;# CLAUDE.md: project instructions for Claude Code&lt;/span&gt;
&lt;span class="c"&gt;&amp;lt;!-- Keep this file under ~200 lines. HTML comments are stripped before Claude sees them. --&amp;gt;&lt;/span&gt;

@AGENTS.md

&lt;span class="gu"&gt;## Claude Code specifics&lt;/span&gt;
&lt;span class="p"&gt;-&lt;/span&gt; Use plan mode before touching more than 3 files.
&lt;span class="p"&gt;-&lt;/span&gt; For searches that would flood the context, delegate to a subagent
  and ask for a summary with file paths.
&lt;span class="p"&gt;-&lt;/span&gt; Before calling a task done, run the checks in "Definition of done"
  and paste the command output summary.

&lt;span class="gu"&gt;## Things that went wrong before&lt;/span&gt;
&lt;span class="p"&gt;-&lt;/span&gt; Do not "fix" failing tests by loosening assertions or adding &lt;span class="sb"&gt;`.skip`&lt;/span&gt;.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Two details: imports are relative to &lt;code&gt;CLAUDE.md&lt;/code&gt; and can nest up to four hops. Block-level HTML comments are stripped before injection, so notes for humans cost no context. Run &lt;code&gt;/context&lt;/code&gt; to confirm which memory files actually loaded.&lt;/p&gt;

&lt;h3&gt;
  
  
  .cursor/rules/00-core.mdc
&lt;/h3&gt;

&lt;p&gt;Cursor project rules must be &lt;code&gt;.mdc&lt;/code&gt; files in &lt;code&gt;.cursor/rules/&lt;/code&gt;. A plain &lt;code&gt;.md&lt;/code&gt; file there is ignored. The always-on core rule just points to AGENTS.md and adds a few hard limits:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight markdown"&gt;&lt;code&gt;&lt;span class="nn"&gt;---&lt;/span&gt;
&lt;span class="na"&gt;description&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="s"&gt;Core&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;working&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;agreement&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;for&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;every&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;Agent&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;chat&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;in&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;this&lt;/span&gt;&lt;span class="nv"&gt; &lt;/span&gt;&lt;span class="s"&gt;repo"&lt;/span&gt;
&lt;span class="na"&gt;alwaysApply&lt;/span&gt;&lt;span class="pi"&gt;:&lt;/span&gt; &lt;span class="kc"&gt;true&lt;/span&gt;
&lt;span class="nn"&gt;---&lt;/span&gt;

&lt;span class="p"&gt;-&lt;/span&gt; Follow &lt;span class="sb"&gt;`AGENTS.md`&lt;/span&gt; at the repo root for commands, layout and definition of done.
&lt;span class="p"&gt;-&lt;/span&gt; Before editing, list the files you plan to change. Keep the diff limited to the task.
&lt;span class="p"&gt;-&lt;/span&gt; Never read, print, or edit &lt;span class="sb"&gt;`.env*`&lt;/span&gt;, &lt;span class="sb"&gt;`*.pem`&lt;/span&gt;, &lt;span class="sb"&gt;`*.key`&lt;/span&gt; or credential files.
&lt;span class="p"&gt;-&lt;/span&gt; Finish every task with: what changed, how you verified it (exact commands), open risks.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Stack-specific rules go in separate &lt;code&gt;.mdc&lt;/code&gt; files that attach by &lt;code&gt;globs&lt;/code&gt;, so they only cost tokens when a matching file is in context.&lt;/p&gt;

&lt;h3&gt;
  
  
  .codex/config.toml
&lt;/h3&gt;

&lt;p&gt;Codex instructions come from &lt;code&gt;AGENTS.md&lt;/code&gt;. &lt;strong&gt;Behaviour&lt;/strong&gt; (sandbox, approvals, subagents) lives in &lt;code&gt;config.toml&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight toml"&gt;&lt;code&gt;&lt;span class="py"&gt;approval_policy&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s"&gt;"on-request"&lt;/span&gt;
&lt;span class="py"&gt;sandbox_mode&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s"&gt;"workspace-write"&lt;/span&gt;
&lt;span class="py"&gt;web_search&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s"&gt;"cached"&lt;/span&gt;

&lt;span class="nn"&gt;[agents]&lt;/span&gt;
&lt;span class="py"&gt;max_concurrent_threads_per_session&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;4&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Codex loads a project's &lt;code&gt;.codex/&lt;/code&gt; layers only when you trust the project.&lt;/p&gt;

&lt;h2&gt;
  
  
  When the agent "ignores" the rules
&lt;/h2&gt;

&lt;p&gt;If an agent ignores your conventions, the cause is almost always that the rule file is too long, vague or contradictory, or wasn't loaded at all. Check before rewriting anything:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Claude Code: &lt;code&gt;/context&lt;/code&gt; and &lt;code&gt;/memory&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;Codex: &lt;code&gt;/status&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;Cursor: Customize → Rules&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Then shorten the file, make the instructions verifiable, and remove conflicts. One canonical file makes that much easier, because there's only one place to fix.&lt;/p&gt;

&lt;h2&gt;
  
  
  Wrap-up
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;AGENTS.md&lt;/code&gt; is canonical. &lt;code&gt;CLAUDE.md&lt;/code&gt; and &lt;code&gt;.cursor/rules&lt;/code&gt; stay thin and point to it.&lt;/li&gt;
&lt;li&gt;In &lt;code&gt;CLAUDE.md&lt;/code&gt;, always add an explicit &lt;code&gt;@AGENTS.md&lt;/code&gt; import.&lt;/li&gt;
&lt;li&gt;Put commands first, use verifiable instructions, and give every agent the same definition of done.&lt;/li&gt;
&lt;li&gt;Keep tool behaviour (permissions, sandbox, hooks) in each tool's own config, not in the instructions.&lt;/li&gt;
&lt;/ul&gt;




&lt;p&gt;Free excerpt: &lt;a href="https://lirenplr.gumroad.com/l/zocmzn" rel="noopener noreferrer"&gt;https://lirenplr.gumroad.com/l/zocmzn&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;&lt;em&gt;This article is adapted from the **AI Coding Agent Workflow Pack&lt;/em&gt;&lt;em&gt;: a 37-page guide plus a drop-in template bundle (the full AGENTS.md, CLAUDE.md, all four Cursor rule types, Codex config, 10 copy-paste workflows and a security checklist). Every file name and flag was checked against the official docs in October 2026. &lt;a href="https://lirenplr.gumroad.com/l/xymroh" rel="noopener noreferrer"&gt;Get it on Gumroad ($24)&lt;/a&gt;. I post tested agent workflows as &lt;a href="https://x.com/Mars_Peakul" rel="noopener noreferrer"&gt;@Mars_Peakul&lt;/a&gt; on X.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>ai</category>
      <category>productivity</category>
      <category>programming</category>
      <category>tutorial</category>
    </item>
  </channel>
</rss>
