DEV Community: Maxi Contieri

AI Coding Tip 022 - Give AI a Harness to Work With

Maxi Contieri — Tue, 02 Jun 2026 11:00:00 +0000

Make the AI Work Inside Boundaries, Not Outside Them

TL;DR: Install your harness before prompting: the structure you set up first is what turns an impulsive AI into a safe, steerable collaborator.

Common Mistake ❌

You open a fresh chat and type a bare prompt.

No AGENTS.md loaded.

No committed baseline.

No test requirement stated.

No read-only planning step.

The AI starts writing code immediately.

You read the output, it looks plausible, and you accept it.

Six weeks later something breaks in production.

You can't trace why because there is no harness to tell you what the AI changed, why, or what rules it followed.

Problems Addressed 😔

The AI makes plausible-looking changes across multiple files with no safe revert point.
Code passes local tests but breaks production because no harness enforced a real definition of done.
Every session starts blank and the AI reverts to its own style, ignoring your project conventions.
Context pollution and hallucinations accumulate when no structure limits the scope of each task.
Destructive changes (deleted guards, introduced anti-patterns) go undetected without automated feedback.
The AI makes tests pass by deleting them or weakening their assertions instead of fixing the actual defect.

How to Do It 🛠️

Run /init before your first prompt and create AGENTS.md with your stack, coding standards, build command, and test command.
Commit your code before every AI session so you always have a clean git reset --hard checkpoint.
Tell the AI explicitly that all tests must pass before the task is done, and include the test command in AGENTS.md. Some tools support the /goal command
Require the AI to read, explain, and propose a plan before touching any file, then define done with a spec before it writes any code.
Split AGENTS.md into nested files by area: root file for global rules, subdirectory files for area-specific constraints.
Create a 20-50 line skill file for each repeating task type and load only the relevant skill, not the whole rulebook.
Add an "AI Context" section to every PR with the decisive prompt, active skills, what the AI tried first, and any corrections you made.
Update AGENTS.md with every new rule revealed by a merged PR before you close the branch.
Declare test files and critical contracts as read-only in AGENTS.md so the only path to a passing test suite is fixing the implementation, never editing the tests.

Benefits 🎯

Safe revert point: You can always undo AI changes cleanly because a commit checkpoint exists before every session.
Consistent style: The AI reads AGENTS.md at startup and follows your project's conventions, not its training defaults.
Machine-enforced definition of done: When the AI must pass your test suite, "done" has an objective, machine-verified meaning.
Reduced hallucinations: A harness limits scope so the AI works on one bounded task at a time instead of drifting across the codebase.
Compounding knowledge: Every PR lesson updates AGENTS.md and the harness improves with every session.

Context 🧠

A harness isn't a limitation.

A horse harness doesn't reduce the horse's power.

It directs massive energy into precise, steerable work.

Without a harness, the horse is dangerous.

With one, the horse plows fields and races on command.

The AI's speed and pattern-matching capability are the energy.

The harness makes that energy productive instead of destructive.

A test harness wraps a unit under test so you can observe and control its behavior.

An AI harness does the same for your assistant: it bounds what the AI can touch and makes every output reviewable.

The parallel is exact: tests provide validation feedback, AGENTS.md is your configuration and fixture, commit-before-prompt is setup and teardown, and CI is the test runner.

Isaac Asimov's Three Laws of Robotics were fiction's first harness: hard rules baked into every robot to bound its behavior.

A robot may not injure a human being or, through inaction, allow a human being to come to harm.
A robot must obey orders given by human beings except where such orders conflict with the First Law.
A robot must protect its own existence as long as such protection doesn't conflict with the First or Second Law.

Your AGENTS.md is the same idea applied to AI coding assistants: explicit rules that constrain behavior and enforce your conventions.

Without constraints, the AI takes the shortest path to a passing test suite.

That path sometimes runs through the test file itself.

It deletes the failing test, or weakens the assertion to assertTrue(true).

Declare your test files and critical contracts as read-only in AGENTS.md.

The AI's only valid exit is fixing the code.

The chat window isn't the source of truth.

Decisions made in a conversation scroll away or get compacted when the session closes.

AGENTS.md, skill files, and commit checkpoints are artifacts that outlive any chat.

A harness externalizes the rules so the AI never starts from zero and every decision leaves a traceable record.

The model is rarely the weak point.

The system around the model is.

A longer prompt doesn't replace a harness.

A harness makes even a short prompt produce consistent and reviewable work because the constraints live in files, not in your memory.

A safety harness doesn't prevent you from working at height.

It lets you work confidently at height because a fall won't be fatal.

The commit-before-prompt pattern is that safety line.

Prompt Reference 📝

Bad Prompt 🚫

Refactor the PaymentProcessor class to use the Null Object pattern.

Good Prompt 👉

Read @PaymentProcessor.php and @tests/PaymentProcessorTest.php.

Don't write any code yet.

Explain how the class handles null payments today.

Then write a plan to introduce the Null Object pattern

following the rules in AGENTS.md and skills/php-clean-code.md.

Wait for my approval before making any changes.

After I approve:
Create a failing test for the Null Object.

Apply the change.
Run all tests until they pass.

Considerations ⚠️

Simple tasks don't need a full harness.

A CSS tweak, a typo fix, or a one-liner change doesn't require AGENTS.md and a planning step.

The harness is proportional to the complexity and risk of the task.

The harness degrades if you stop maintaining it.

Every session that teaches the AI something new must update AGENTS.md, or the knowledge vanishes with the chat.

A harness without automated feedback is incomplete.

Configuration files alone aren't enough.

Tests, CI, and linters must enforce what AGENTS.md declares.

A session that produces hundreds of lines of change isn't always a win.

It can be review debt transferred to the next human who opens the PR.

If a single session grows beyond what a reviewer can absorb in one sitting, split the output into smaller, chained units before opening the pull request.

Type 📝

[X] Semi-Automatic

Limitations ⚠️

The harness requires upfront investment in AGENTS.md, skills, and test setup, which outweighs the benefit on small throwaway projects.

Tags 🏷️

Safety

Level 🔋

[X] Intermediate

Related Tips 🔗

Maxi Contieri

Jan 6

AI Coding Tip 001 - Commit Before Prompt

#ai #development #coding #webdev

Comments

3 min read

Maxi Contieri

Jan 20

AI Coding Tip 003 - Force Read-Only Planning

#ai #programming #chatgpt #code

Comments

3 min read

Maxi Contieri

Mar 18

AI Coding Tip 011 - Initialize Agents.md

#ai #programming

Comments

3 min read

Maxi Contieri

Feb 24

AI Coding Tip 008 - Use Spec-Driven Development with AI

#ai #programming #coding

Comments

4 min read

Conclusion 🏁

You wouldn't give a power tool to someone with no safety equipment and no instructions.

You give them the tool, the harness, and the training first.

Do the same for your AI.

Install the harness before the first prompt, maintain it after every PR, and the AI becomes a precise, reviewable collaborator instead of a fast source of technical debt.

More Information ℹ️

Test Harness (Wikipedia)

Three Laws of Robotics (Wikipedia)

Claude Code Memory and AGENTS.md

Goal Command

Also Known As 🎭

AI-Safety-Net
Prompt-Guardrails
AI-Scaffolding
Bounded-AI-Workflow

Tools 🧰

Disclaimer 📢

The views expressed here are my own.

I am a human who writes as best as possible for other humans.

I use AI proofreading tools to improve some texts.

I welcome constructive criticism and dialogue.

I shape these insights through 30 years in the software industry, 25 years of teaching, and writing over 500 articles and a book.

This article is part of the AI Coding Tip series.

Maxi Contieri

Jan 21

AI Coding Tips

#webdev #ai #programming #beginners

Comments

1 min read

AI Coding Tip 021 - Avoid Comprehension Debt

Maxi Contieri — Tue, 26 May 2026 11:00:00 +0000

Stop shipping code you can't explain.

TL;DR: Merging code you don't understand creates comprehension debt that compounds until your team can no longer maintain it.

Common Mistake ❌

You ask the AI to implement a feature.

The code looks clean.

The tests are green.

You merge it.

Six weeks later, a defect appears in that module.

Nobody on your team can explain how it works.

You ask the AI again.

You merged without understanding.

You built both functional and comprehension debt.

Problems Addressed 😔

You lose the ability to debug without the AI.
Your team can't onboard new members into AI-generated modules.
Design decisions become invisible and accumulate silently.
You mistake "tests passing" for "code understood."
Your velocity metrics look great while comprehension quietly collapses underneath.
A junior developer can now generate code faster than a senior engineer can audit it.
The quality gate you relied on disappears.

How to Do It 🛠️

Ask the AI to explain every non-trivial block before you accept it.
Close the chat and rewrite the explanation in your own words in a comment or ADR.
Ask the AI "what assumptions did you make here?" for each function it generates.
Run a 10-minute AI blackout: try to explain the module to a colleague without reopening the chat.
Add a comprehension check step in your PR template: "Can you explain this change in 3 sentences?"
Use the AI for conceptual inquiry: ask why as often as you ask how.
Identify your load-bearing decisions: the choices that, if wrong, will cost you weeks.
Keep a short decisions.md file with one sentence per architectural decision the AI made on your behalf.

Benefits 🎯

Debuggability: You can fix defects without reopening the AI chat because you understand the system.
Onboarding speed: New teammates can read your decisions file and understand why the code exists.
Reduced rework: You catch flawed assumptions before they reach production.
Honest velocity: Your speed metric reflects real output, not deferred understanding.
AI supervision skill: Research shows that cognitive engagement with AI preserves learning outcomes even when you receive AI assistance.

Context 🧠

Comprehension debt is the growing gap between how much code exists in your system and how much any human genuinely understands.

Addy Osmani named and described this pattern in March 2026.

Unlike technical debt, comprehension debt breeds false confidence.

The codebase looks clean.

The tests pass.

The reckoning arrives quietly, at the worst possible moment.

A research team at Anthropic ran a randomized controlled trial with 52 software engineers learning a new library.

The group using AI completed the task in the same time as the control group, but scored 17% lower on a follow-up comprehension quiz (42% vs. 57%) (Shen and Tamkin, Anthropic, 2026).

The biggest drops were in debugging ability.

The researchers found six distinct AI interaction patterns.

Three of them involve cognitive engagement and preserve learning outcomes even when you receive full AI assistance.

The tool doesn't destroy understanding.

How you use it does.

You can also think of comprehension debt as a speed asymmetry problem.

AI generates code far faster than you can evaluate it.

When you write code, the review process is a bottleneck, but a productive one.

Reading the PR forces comprehension.

AI-generated code breaks that feedback loop.

The volume is too high.

The output is syntactically clean and superficially correct: exactly the signals that used to make you feel safe to merge.

Surface correctness isn't systemic correctness.

Prompt Reference 📝

Bad Prompt 🚫

Add Redis caching to the UserRepository class.

Good Prompt 👉

Add Redis caching to the UserRepository class.

After you implement it:
1. Explain every non-trivial decision you made.

2. List the assumptions you made about cache expiration,
   key naming, and invalidation strategy.

3. Identify any load-bearing decisions: choices that,
   if wrong, would require a full rewrite.

4. Write one sentence per decision in decisions.md format
   so my team understands why the code works this way.

Considerations ⚠️

Tests are necessary, but they aren't sufficient.

A test suite can only cover behavior you thought to specify.

Nobody writes a test for a behavior nobody imagined.

When the AI updates hundreds of tests to match new behavior, you must ask: "Were all those changes correct?"

Only comprehension can answer that question.

Tests can't.

Specs help, but they aren't a substitute for review.

A spec detailed enough to fully describe a program is more or less the program, written in a non-executable language.

Keep your AI context window short and your decisions file honest.

You document decisions, not transcripts.

Type 📝

[X] Semi-Automatic

Limitations ⚠️

Comprehension checks add time to each PR.

Your team must agree to slow down a little to stay safe.

Tags 🏷️

Knowledge Management

Level 🔋

[X] Intermediate

Related Tips 🔗

Maxi Contieri

Feb 13

AI Coding Tip 006 - Review Every Line Before Commit

#ai #programming #development #softwaredevelopment

Comments 1

7 min read

Maxi Contieri

May 12

AI Coding Tip 019 - Tell the AI Why, Not Just What

#ai #coding #llm #productivity

Comments 3

4 min read

Conclusion 🏁

AI makes code cheap to generate.

It doesn't make understanding cheap to skip.

Every time you merge code you can't explain, you borrow from your future self.

You'll pay for comprehension sooner or later.

Pay it now, with curiosity.

More Information ℹ️

Comprehension Debt: The Hidden Cost of AI-Generated Code by Addy Osmani

How AI Impacts Skill Formation, Shen and Tamkin, Anthropic (arXiv 2601.20245)

Comprehension Debt on O'Reilly Radar

Mitigating Epistemic Debt in Generative AI-Scaffolded Programming (arXiv 2602.20206)

AI Technical Debt Compounds: Augment Code Guide

Also Known As 🎭

Cognitive-Debt
AI-Comprehension-Gap
Invisible-Technical-Debt
Epistemic-Debt

Disclaimer 📢

The views expressed here are my own.

I am a human who writes as best as possible for other humans.

I use AI proofreading tools to improve some texts.

I welcome constructive criticism and dialogue.

I shape these insights through 30 years in the software industry, 25 years of teaching, and writing over 500 articles and a book.

This article is part of the AI Coding Tip series.

Maxi Contieri

Jan 21

AI Coding Tips

#webdev #ai #programming #beginners

Comments

1 min read

AI Coding Tip 020 - Create a Second Brain

Maxi Contieri — Tue, 19 May 2026 11:00:00 +0000

Build a Persistent Memory Layer Your AI Can Actually Use

TL;DR: Use Obsidian with Markdown notes, YAML metadata, and direct AI file access to build a Second Brain with LLMs that gives your tools persistent project context.

Common Mistake ❌

You paste a snippet of code or a problem description into an AI chat, get a good answer, and close the tab.

The next week you face the same problem again.

You search your chat history, find nothing useful, and paste the same snippet again.

Your AI starts fresh every session with zero memory of what you built, decided, or debugged before.

Problems Addressed 😔

You repeat yourself constantly because context resets between sessions and your AI remembers nothing.
You lose architectural decisions, debugging notes, meeting commitments, and design rationale after each conversation ends.
Your AI gives generic answers because it lacks the specific context of your project and past decisions.
Mental load accumulates as you juggle multiple projects, notifications, and context switches simultaneously.
You lose track of decisions made weeks ago without a structured retrieval system.
As you age or face cognitive overload, you forget context between sessions, repeat past mistakes, and lose the thread of long-running projects.
Notification fatigue builds when every system demands your attention in real time instead of on your schedule and you forget what you were searching for.

How to Do It 🛠️

Choose a local Markdown tool like Obsidian, Logseq, Foam, or Tolaria to store all your knowledge as plain .md files you own and control.
Organize your vault using the PARA system: Projects (active work with deadlines), Areas (ongoing responsibilities), Resources (reference material), and Archives (inactive items).
Write atomic Zettelkasten notes: one idea per file, with a unique identifier and explicit links that explain why two concepts relate, not just what they are.
Add YAML front matter to every note so your AI gets searchable, structured metadata it can query and filter:

---
title: "JWT Authentication Design"
type: architecture-decision
status: approved
component: auth-service
tags: [security, backend]
created: 2018-12-09
related: ["OAuth Flow", "Session Management"]
---

Use Dataview or Obsidian Bases to query your vault like a database and surface all tasks due today, pending decisions, or notes grouped by component with a single dynamic query; every note is a record with metadata and legible text.
Give your AI direct access to all your vault as local files so Claude, Devin, and Codex can read your entire codebase and notes simultaneously.
Create a AGENTS.md in each sub-project that points to the relevant vault sections, following the nested agents pattern from AI Coding Tip 014.
Dictate notes on the go using voice input and paste the transcript into your vault to capture context in real time without interrupting your flow.
Sync your vault to mobile and tablet using Obsidian Sync, Dropbox, OneDrive, or Syncthing so your Second Brain travels with you everywhere.
Set up OpenClaw or a local LLM (Ollama or LM Studio) to index your vault and answer questions via Telegram or WhatsApp, as a private assistant that never sends your data to the cloud.
Ask your AI to scan your vault periodically for orphaned notes, missing connections, and hidden patterns, acting as a tireless librarian that reorganizes your knowledge network over time without falling into vault-design paralysis.
Bootstrap your vault from your existing knowledge: ask ChatGPT, Claude, Grok, or Gemini to summarize and export your most relevant past conversations as Markdown notes, since you already have a Second Brain scattered across chat history waiting to be harvested.

Benefits 🎯

Persistent Context: Your AI starts every session knowing your architecture, past decisions, and current priorities instead of starting blank.
Pattern Discovery: The LLM finds connections between notes you wrote months apart and surfaces forgotten solutions to current problems.
Focus Protection: You capture every interruption into your inbox and process it on your schedule, eliminating notification fatigue.
Memory Extension: You can retrieve exact decisions and reasoning from months ago without relying on biological memory alone, making it especially valuable for senior developers, people with attention challenges, or anyone whose cognitive load has grown beyond what one brain can hold.
Privacy by Default: When you use local models like Ollama with OpenClaw, your notes, code, and queries never leave your machine.
Compounding Knowledge: Every note you add makes your Second Brain denser: the more you use it, the more valuable it becomes.
Mobile Access: You can query and update your knowledge base from any device, making your Second Brain available wherever you work.
Distraction-Free Writing: You work in plain text files with minimal formatting, much like zenware, so you stay focused on ideas instead of tools.
Visual Graph: You can open Obsidian's Graph View to see all your notes as a visual network where nodes are notes and edges are links, revealing clusters, hub concepts, and hidden connections at a glance.

Context 🧠

Tiago Forte's "Building a Second Brain" methodology introduced the CODE framework: Capture, Organize, Distill, Express.

For developers, this maps directly to how you learn, document, and reuse knowledge across projects.

Niklas Luhmann, a sociologist who wrote over 50 books, developed the Zettelkasten method using a physical slip box of interconnected atomic notes.

Your Obsidian vault is that slip box, and your AI can search, analyze, and extend it at any time.

LLMs have three types of memory: parametric (knowledge encoded during training), working (the current context window), and external (your files on disk).

Your Second Brain fills the external memory layer and gives the AI permanent access to your project-specific knowledge that survives every session reset.

Just as neural networks in LLMs store patterns in weights, your Second Brain stores patterns in linked Markdown files, extending the model's memory with your lived experience as a developer.

Andrej Karpathy captured this architecture in one sentence: "Obsidian is the IDE; the LLM is the programmer; the wiki is the codebase."

The front matter you add to each note acts as structured metadata that significantly improves how AI retrieves and ranks relevant information.

RAG (Retrieval-Augmented Generation) pipelines embed your notes as vectors and return the most semantically similar ones when you ask a question, injecting them directly into the AI's context window.

I borrowed this idea many years ago from @ernesto Kiszkurno and have written more than 500 technical articles since then.

Prompt Reference 📝

Bad Article 🚫

Create a note about the movie
"Howl's Moving Castle".

Good Article 👉

---
title: "Howl's Moving Castle"
type: movie-note
status: draft
director: Hayao Miyazaki
year: 2004
genre: [fantasy, animation, anti-war]
rating: 9/10
tags: [ghibli, miyazaki, adaptation]
related: ["Studio Ghibli", "Diana Wynne Jones"]
created: 2026-05-16
expected publish date: 2026-06-12
---

## Poster
![Howl's Moving Castle](Howls-moving-castleposter.jpg)

## Summary
Two or three lines describing the plot without
spoiling the ending.

## Themes to Explore
Bullet list of ideas: anti-war message,
identity and transformation, Sophie's arc,
Miyazaki's pacifism compared to the novel.

## Characters
Use wikilinks: [Howl], [Sophie Hatter],
[Calcifer], [The Witch of the Waste].

## Article Ideas
Numbered list of angles for a critical article:
compare Miyazaki's changes from the Diana Wynne
Jones novel, analyze the anti-war allegory,
explore the feminist reading of Sophie's curse.

## Related Notes
[Studio Ghibli filmography]
[Diana Wynne Jones bibliography]
[War themes in animation]

Considerations ⚠️

Keep your notes in plain Markdown files, not HTML (despite current trends) or proprietary formats.

Markdown is readable by both humans and LLMs, diffs cleanly in Git, and works with every static site generator.

Don't use MCP connectors or remote APIs to give your AI access to your vault.

Point it directly at local files instead.

Direct file access is faster, cheaper, and requires no extra infrastructure.

The AGENTS.md files you create per project are part of your Second Brain, not separate from it.

If you have privacy concerns about cloud AI providers reading your notes, run a local model with Ollama or LM Studio through OpenClaw.

Your data never leaves your machine or private cloud.

Mind maps and Canvas diagrams in Obsidian help you visualize codebase architecture and sprint planning spatially, while the linked Markdown notes behind each node stay searchable by your AI.

Your files are local.

Nobody can see them, nobody can index them, and you can open any note with the simplest text editor in the world.

If you use a cloud AI model instead of a local one, you can add a guardrail to restrict what files the AI can read, so sensitive notes never leave your control.

Type 📝

[X] Semi-Automatic

Limitations ⚠️

Large vaults with thousands of notes can slow down semantic search and local LLM indexing on low-end hardware.

Front matter requires discipline to maintain consistently: inconsistent metadata reduces query quality over time.

Local LLMs powerful enough to reason over a large vault require significant RAM (16 GB minimum, 32 GB recommended).

Tags 🏷️

Knowledge Management

Level 🔋

[X] Intermediate

Related Tips 🔗

Maxi Contieri

Mar 10

AI Coding Tip 010 - Access All Your Code

#webdev #ai #programming #beginners

Comments

4 min read

Maxi Contieri

Apr 7

AI Coding Tip 014 - Use Nested AGENTS.md Files

#ai #webdev #programming #productivity

Comments

4 min read

Maxi Contieri

May 12

AI Coding Tip 018 - Use Voice-Driven-Development

#ai #webdev #programming #tutorial

Comments

4 min read

Conclusion 🏁

Your biological brain is for having ideas, not storing them.

Build a Second Brain from local Markdown files and give your AI direct access to it.

You get persistent context, pattern discovery, and a knowledge base that compounds every time you use it. 🧠

More Information ℹ️

Zettelkasten Introduction

Obsidian - Local Markdown Knowledge Base

// Detect dark theme var iframe = document.getElementById('tweet-2039805659525644595-193'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=2039805659525644595&theme=dark" }

Front Matter in Real books

Dataview Plugin for Obsidian

Andrej Karpathy LLM Wiki Pattern

Foam - Second Brain for VS Code

Building a Second Brain - Tiago Forte

Second Brain (Spanish)

Also Known As 🎭

Personal-Knowledge-Management
AI-Memory-Extension
Developer-Second-Brain
Local-Knowledge-Base

Tools 🧰

Disclaimer 📢

The views expressed here are my own.

I am a human who writes as best as possible for other humans.

I use AI proofreading tools to improve some texts.

I welcome constructive criticism and dialogue.

I shape these insights through 30 years in the software industry, 25 years of teaching, and writing over 500 articles and a book.

This article is part of the AI Coding Tip series.

Maxi Contieri

Jan 21

AI Coding Tips

#webdev #ai #programming #beginners

Comments

1 min read

AI Coding Tip 018 - Use Voice-Driven-Development

Maxi Contieri — Tue, 12 May 2026 11:00:00 +0000

Talk twice as fast as you type, and create richer prompts with less effort.

TL;DR: Dictate your prompts instead of typing them to speak twice as fast and give more context.

Common Mistake ❌

You write detailed prompts by hand, word by word, staying at your desk.

You restrict yourself to slow keyboard-based interaction with AI tools because that's how you have always worked.

You assume voice input is still unreliable because of syntax complexity (brackets, semicolons, language-specific quirks).

Problems Addressed 😔

Typing speed limits the depth and context of your prompts, hurting AI output quality.
You spend 80% of your job thinking, designing, and communicating, yet you treat writing as a bottleneck instead of optimizing it.
Staying chained to your desk during focused work reduces mobility, creativity, and wellbeing.
You miss opportunities to rubber-duck ideas by speaking them aloud to an AI agent.
You can dictate in seconds complex prompts that would take minutes to type.

How to Do It 🛠️

Enable voice mode in your tool /voice or similar.
Start dictating your prompt with accuracy in a long prompt with context.
Speak naturally in English, explaining your request with full context, constraints, and examples.
Release the key when you finish, and your tool will transcribe and process your input.
If your tool doesn't support voice mode, install Whispr Flow or similar and configure your preferred voice hotkey.
Use Speech-To-Text in any application (terminal, email, code editor, documents) by holding your hotkey and speaking.
Start with one scenario: dictating a single prompt.
Expand voice into your entire workflow as it becomes natural: specs, documentation, brainstorming, thinking aloud.

Benefits 🎯

Speed: You speak at 150 words per minute versus typing at 80 words per minute, nearly doubling your prompt composition speed.
Richer Prompts: Speaking encourages thinking aloud, producing more nuanced context and backstory than typed prompts, which improves AI output quality.
Rubber-Ducking: Explaining a problem verbally to an AI agent often surfaces solutions without explicit effort, just like talking to a colleague.
Mobility: You can draft specs, think through architecture, or brainstorm ideas while walking, commuting, or in environments that boost creativity.
Health: You spend less time hunched over your keyboard.

Your posture improves and you move more.

Cognitive Flow: You stay in thinking mode instead of switching to typing mode.

Your mental focus stays on the problem.

Context 🧠

Why Voice Works Now

Historically, voice-to-code failed because speech recognition couldn't parse syntax.

Today, AI understands your intent in natural language and translates it into precise code.

Modern AI assistants like Claude can infer what you mean even when you speak conversationally ("can you fix the bug where users see a blank screen after login") without needing you to type angle brackets or semicolons.

Prompt Reference 📝

Bad Prompt 🚫

Fix the code

# (Typing it in the console)

Good Prompt 👉

# Dictated by /voice

I have a user authentication function that's failing.

It is highlighted in the editor

When users try to log in with valid credentials

The system returns a 500 error instead of creating a session.

The error logs show it's happening in the password validation step. 

I need you to review the authentication logic
identify why the validation is failing
and provide a fix that includes proper error handling
for invalid credentials and missing database connections.

Considerations ⚠️

Dictation may feel awkward the first time because you aren't used to speaking technical requests aloud.

You may ramble or repeat yourself slightly when dictating, but the AI agent will extract what it needs.

Voice works best for high-level requests, architecture decisions, and design thinking, not for precise syntax correction.

You still need to review AI output before committing, just as you would with typed prompts.

Type 📝

[X] Semi-Automatic

Limitations ⚠️

Voice input works best in quiet environments; background noise reduces accuracy.

Some very large or precise code changes may be faster to type than dictate.

You need to speak them in English, or change the overall language.

Most tools won't let you have multiple voice languages.

You need to invest time learning which voice tool works best for your workflow and hardware.

Level 🔋

[X] Beginner

Tags 🏷️

Context Window

Related Tips 🔗

Maxi Contieri

Feb 13

AI Coding Tip 006 - Review Every Line Before Commit

#ai #programming #development #softwaredevelopment

Comments 1

7 min read

Maxi Contieri

Jan 20

AI Coding Tip 003 - Force Read-Only Planning

#ai #programming #chatgpt #code

Comments

3 min read

Maxi Contieri

Feb 4

AI Coding Tip 005 - Keep Context Fresh

#webdev #programming #ai #tutorial

Comments

4 min read

Maxi Contieri

Jan 13

AI Coding Tip 002 - Prompt in English

#programming #ai #webdev

Comments

3 min read

Tools 🧰

Claude Code with /voice command

Whispr Flow

ChatGPT Voice Mode

Conclusion 🏁

Typing is no longer the bottleneck.

You speak twice as fast as you type, and AI understands natural language.

Use voice to dictate prompts, unlock mobility, improve wellbeing, and create richer input for better code generation.

Start with one prompt today.

More Information ℹ️

Claude Code Documentation

Whispr Flow

ChatGPT Voice Mode

Rubber Duck Debugging

Also Known As 🎭

Voice-To-Code
Dictation-Driven-Development
Speech-Based-Prompting

Disclaimer 📢

The views expressed here are my own.

I am a human who writes as best as possible for other humans.

I use AI proofreading tools to improve some texts.

I welcome constructive criticism and dialogue.

I shape these insights through 30 years in the software industry, 25 years of teaching, and writing over 500 articles and a book.

This article is part of the AI Coding Tip series.

Maxi Contieri

Jan 21

AI Coding Tips

#webdev #ai #programming #beginners

Comments

1 min read

AI Coding Tip 019 - Tell the AI Why, Not Just What

Maxi Contieri — Tue, 12 May 2026 11:00:00 +0000

State your reasons before your prompt and the AI will solve the right problem.

TL;DR: Tell the AI your reason before your request to get solutions that match your real constraints.

Common Mistake ❌

You send commands to the AI without context.

"Refactor this."

"Optimize this query."

"Add error handling."

The AI complies, but returns a generic (and probably hallucinated) solution that solves the average case, not your specific one.

You spend the next three messages correcting the trade-offs you never mentioned.

Problems Addressed 😔

The LLM has dozens of valid solutions for any request and picks the most statistically common one without your context.
You get correct (but wrong) results: technically valid code that doesn't fit your constraints.
You iterate more than necessary because the AI guessed wrong about what mattered.
The model makes trade-offs you didn't intend, favoring speed when you needed readability.
When the AI doesn't know the constraint, it can't explain why it chose a specific approach.

How to Do It 🛠️

Identify the real reason behind your request before you type it.
Add one sentence explaining the constraint or goal before your request.
Specify the limiting factor: performance, memory, audience, team skill level, or deadline.
Name the trade-off that matters most to you.
Include who will use or maintain the result.
Force yourself to enter plan mode to reason together.

Benefits 🎯

Better Trade-offs: The LLM navigates to solutions that match your actual constraints instead of the generic average.
Fewer Iterations: You get the right solution in the first attempt instead of correcting trade-offs after the fact.
Principled Decisions: The AI can explain why it chose a specific approach because it knows what you optimized for.
Domain-Aware Results: Context enables domain-specific patterns that generic requests never trigger.
Smarter Refactoring: Research shows that adding motivation to refactoring requests improves success from 15.6% to 86.7%.

Context 🧠

Why the Why Changes Everything

For any given coding problem, the LLM can give you dozens of valid solutions.

Each trades off different qualities: speed vs. memory, readability vs. performance, simplicity vs. flexibility.

Without a reason, the model defaults to the most statistically common solution from its training data.

That solution works for the generic case.

It almost never matches your specific constraints.

When you add the why, the model reweights the entire solution space toward what matters to you.

"Refactor this function" and "Refactor this function because you are deploying to edge devices with 512MB RAM" activate completely different reasoning paths.

The second prompt forces the model to consider memory-efficient algorithms, smaller data structures, and lazy loading patterns.

More precise advice like "never use ellipses because this will be read by text-to-speech" is better than just "never use ellipses."

The same principle applies to every coding request.

When you avoid comments, you document only design decisions.

This is another example of why you need to add the why.

Modern models have more reasoning, and you can check the approach, not just the result.

Prompt Reference 📝

Bad Prompt 🚫

Refactor this function

Good Prompt 👉

Refactor this function
because you are deploying to mobile devices
with limited memory (512MB RAM).

The trade-off that matters most
is memory usage over speed.

Many developers will maintain this code.
Keep it readable.

Avoid heavy data structures
or lazy-loading patterns
that require deep knowledge of the framework.

Considerations ⚠️

One clear reason is enough.

You don't need to write a long paragraph.

The why should describe the constraint, not the implementation.

Don't confuse "why" with "what".

Type 📝

[X] Semi-Automatic

Limitations ⚠️

Adding context makes your prompts longer.

You need to know your own constraints before you can explain them to the AI.

Some requests genuinely have no specific constraint.

In those cases, the generic solution is fine.

Level 🔋

[X] Beginner

Tags 🏷️

Prompt Engineering

Related Tips 🔗

Maxi Contieri

Jan 13

AI Coding Tip 002 - Prompt in English

#programming #ai #webdev

Comments

3 min read

Maxi Contieri

Feb 4

AI Coding Tip 005 - Keep Context Fresh

#webdev #programming #ai #tutorial

Comments

4 min read

Maxi Contieri

Jan 20

AI Coding Tip 003 - Force Read-Only Planning

#ai #programming #chatgpt #code

Comments

3 min read

Maxi Contieri

Feb 13

AI Coding Tip 006 - Review Every Line Before Commit

#ai #programming #development #softwaredevelopment

Comments 1

7 min read

Conclusion 🏁

Every coding problem has multiple valid solutions.

The AI picks the generic one unless you tell it which trade-off matters.

One sentence explaining your constraint shifts the model from solving the average problem to solving your exact problem.

Tell the AI why.

More Information ℹ️

Chain-of-Thought Prompting Elicits Reasoning in Large Language Models

Effective Context Engineering for AI Agents

Prompting Best Practices - Claude API Docs

LLM-Driven Code Refactoring: Opportunities and Limitations

Best Practices for Prompt Engineering with the OpenAI API

Also Known As 🎭

Reason-Driven-Prompting
Constraint-First-Prompting
Motivation-Aware-Prompting

Disclaimer 📢

The views expressed here are my own.

I am a human who writes as best as possible for other humans.

I use AI proofreading tools to improve some texts.

I welcome constructive criticism and dialogue.

I shape these insights through 30 years in the software industry, 25 years of teaching, and writing over 500 articles and a book.

This article is part of the AI Coding Tip series.

Maxi Contieri

Jan 21

AI Coding Tips

#webdev #ai #programming #beginners

Comments

1 min read

AI Coding Tip 017 - Ask for the Analyst, Not the Analysis

Maxi Contieri — Tue, 28 Apr 2026 11:00:00 +0000

When you have a lot of data to analyze, Ask for a tool, not a summary.

TL;DR: Ask the AI to write a program that analyzes your data instead of pasting all your data into the prompt.

Common Mistake ❌

You have 50 complex JSON files.

You paste them all into the chat and ask:

Find all users whose orders exceeded $500 in Q3.

The AI struggles.

It hits context limits.

It misses records.

It gives you a hallucinated summary with silent errors.

You don't get analysis.

You get a probabilistic guess.

Problems Addressed 😔

Context window overflow. Large datasets exceed what the model can hold in memory.

It silently drops data.

Silent hallucination. The AI fills gaps with invented numbers when data doesn't fit.

You can't tell which results are real.

No reproducibility. You can't re-run the same "analysis" tomorrow on new data.

Each chat is a one-shot lottery.

No auditability. You can't verify how the AI reached each conclusion.

There is no code trail and debugging.

Wasted tokens. You burn your context window on raw data the model can only partially process.
Non-scalable workflow. When you get 50 more JSON files next week, you start from scratch.

How to Do It 🛠️

Describe your data shape to the AI, not the data itself. Tell it the JSON structure, field names, and types.
State your analysis goal clearly and precisely. ("Find users with total order value > $500 in Q3 2024.")
Ask for a program in your preferred language that reads the files from disk and performs the analysis.
Review the generated code before running it.
Run it locally on your real data.
Iterate. Ask the AI to refine the program if the output needs adjustments.

Benefits 🎯

Unlimited data size. Your program reads files from disk.

It doesn't care if you have 5 files or 5,000.

Reproducible results. You run the same script every week on fresh data and get consistent, verifiable output.
Full auditability. You read the code.

You know exactly what logic produced each result.

Zero hallucination risk on data. The program reads your actual files.

It doesn't invent values.

Speed. A script can process 1,000 JSONs in seconds.

A prompt processes them... poorly.

Trust. You can ask a local tool to find empty folders.

You can also ask for a script to validate them giving examples.

Coverage. You cover your solution and can iterate it later without breaking it.
Reusability. You own the script.

Modify it, schedule it, version-control it, test it, iterate it, share it.

Context 🧠

LLMs are text predictors with a finite context window.

Dumping data into a prompt treats the AI like a database.

It is not a database.

It is a code generator.

Use it as one.

The right mental model: the AI is your senior developer.

You describe the problem.

It writes the tool.

You run the tool.

This pattern scales.

The data-dump pattern doesn't.

Prompt Reference 📝

Bad Prompt 🚫

Here are my 12 JSON files with order data. Each one has
hundreds of records. [pastes 8,000 lines of JSON]

Which users spent more than $500 in Q3?

# You overwhelm the context window. 
# The AI summarizes, guesses, and hallucinates. 
# You can't verify any result. 
# You can't repeat the analysis tomorrow.

Good Prompt 👉

I have a folder with multiple JSON files.
Each file represents one month of orders.

Each JSON has this structure:

{
  "month": "2024-07",
  "orders": [
    {
      "order_id": "ORD-001",
      "user": {
        "name": "Lio Messi",
        "country": "AR"
      },
      "items": [
        {
          "product_id": "PROD-7",
          "name": "Soccer Ball",
          "qty": 2,
          "unit_price": 49.99
        }
      ],
      "status": "completed",
      "created_at": "2022-12-18T12:30:00Z"
    }
  ]
}

Write a Python script that:
1. Reads all .json files from a given folder path
2. Filters orders from Q3 2024 (July, August, September)
3. Computes the total spent per user_id
   (sum of qty by unit_price for completed orders)
4. Prints users whose total exceeds $500, sorted descending
5. Exports the result to a CSV file named q3_top_users.csv

Use pathlib and the standard csv module. No dependencies.

# You describe the shape of the data, not the data itself.
# The AI writes a reliable, auditable, reusable program.
# You run it on your real files.

Considerations ⚠️

Schema accuracy matters.

If you describe the wrong structure, the AI generates code with wrong field names.

Check the generated code against a real sample record.

Edge cases need explicit mention.

Tell the AI about optional keys, inconsistent date formats.

("The status field can be null in some older records.")

Large cross-file joins need memory planning.

Ask the AI to use streaming or chunk-based reads for very large files (>1 GB).

Mention the file size.

This doesn't replace exploratory analysis.

When you genuinely don't know your data shape yet, pasting a small sample (5–10 records) into the prompt is fine.

Use that to understand the shape, then switch to the program approach.

Type 📝

[X] Semi-Automatic

Limitations ⚠️

The generated program needs a local executable environment to run.
Schema descriptions must be accurate.
Bad schema → broken code.
Always verify with a real record.
The AI may not handle deeply nested or polymorphic JSON structures without extra hints.
Add examples of edge-case shapes to your prompt.

Tags 🏷️

Context Window

Level 🔋

[X] Intermediate

Related Tips 🔗

Maxi Contieri

Feb 13

AI Coding Tip 006 - Review Every Line Before Commit

#ai #programming #development #softwaredevelopment

Comments 1

7 min read

Maxi Contieri

Mar 3

AI Coding Tip 009 - Compact Your Context

#webdev #ai #programming #tutorial

Comments 1

4 min read

Maxi Contieri

Mar 10

AI Coding Tip 010 - Access All Your Code

#webdev #ai #programming #beginners

Comments

4 min read

Maxi Contieri

Apr 14

AI Coding Tip 015 - Force the AI to Obey You

#ai #webdev #programming #productivity

Comments

5 min read

Conclusion 🏁

The AI is not a spreadsheet.

It is not a database.

It is a code generator that never gets tired.

When you need to analyze data, you describe the shape of your data and the goal of your analysis.

The AI writes the tool.

You run the tool on real data.

You get verifiable, reproducible, auditable results.

You keep the script.

You run it again next month.

That is how you use AI for data work. 🏁

More Information ℹ️

Lost in the Middle: How Language Models Use Long Contexts

Self-planning Code Generation with Large Language Models

Also Known As 🎭

Generate the tool, run the tool
Ask for the analyzer, not the analysis
Data-driven code generation
Program the solution, don't paste the data

Tools 🧰

Local or cloud development tools

Disclaimer 📢

The views expressed here are my own.

I am a human who writes as best as possible for other humans.

I use AI proofreading tools to improve some texts.

I welcome constructive criticism and dialogue.

I shape these insights through 30 years in the software industry, 25 years of teaching, and writing over 500 articles and a book.

This article is part of the AI Coding Tip series.

Maxi Contieri

Jan 21

AI Coding Tips

#webdev #ai #programming #beginners

Comments

1 min read

AI Coding Tip 016 - Feed Your PR Lessons into the AI Brain

Maxi Contieri — Tue, 21 Apr 2026 11:00:00 +0000

Your PR descriptions are training data for your future self, and for every agent after you.

TL;DR: Improve the AI tools, rules, skills, and workflows you use in every pull request so your team and future agents can learn, reproduce, and improve on every change.

Common Mistake ❌

You write clean code.

The AI helps you ship fast after it understands all your context, and you merge the PR.

You write "Fix bug" as the description.

Two weeks later, nobody knows what prompt produced that fix, which SKILL.md was active, or why you chose that approach over the alternative.

Not your teammates.

Not a new AI agent.

Not you.

The AI's reasoning evaporates the moment you close the chat.

Problems Addressed 😔

You lose the exact prompt that produced a working solution and can't reproduce it.
Future agents start from zero on every PR instead of building on past decisions.
AGENTS.md, SKILL.md, and rules stay generic because nobody tracks which ones actually worked.
Onboarding new developers (or new agents) takes longer because context lives nowhere.
You repeat the same debugging cycles because you never wrote down what failed first.
The team can't measure whether AI assistance improves over time.
Code reviews become guesswork when reviewers can't see the AI's reasoning.
You miss chances to promote a one-off good prompt into a permanent SKILL.md.

How to Do It 🛠️

Add an "AI Context" section to every PR description: Write which agent or tool you used (Claude Code, Copilot, Cursor, Windsurf) and the model version.
Paste or link the key prompt: You don't need the full conversation.

Include the decisive prompt that unlocked the solution.

List the active configuration files: Name every SKILL.md, AGENTS.md section, RULES file, or WORKFLOW.md that shaped the output.
Note what the AI got wrong first: Write one line about the failed attempt before the correct solution.

This is the most valuable information your future self will read.

Flag any manual correction you applied: If you edited the AI output, say so and say why.

This is feedback your team can turn into a new rule.

Update AGENTS.md as part of the PR: If the code change revealed a missing rule or a better workflow step, add it immediately, while context is still fresh.
Update or create SKILL.md entries: If you invented a reusable prompt pattern, extract it into a skill file so every future agent can use it.
Tag the PR with an "ai-assisted" label: This lets you filter and audit AI-assisted changes later for quality review.
Review AI-trace PRs in retros: Once a sprint, pick two PRs with rich AI context and ask what rule or skill you should add.
Ask the LLM to update what it learned: Write a final prompt for the AI to update its own knowledge.

Benefits 🎯

Reusable learning units: Every PR becomes a lesson agents can read and reuse.
Living AGENTS.md: Your rules file grows richer with each merged change instead of staying a static document nobody updates.
Shorter feedback loop: You compress the gap between a good prompt and a reusable skill.
Clearer onboarding: New developers understand why code looks the way it does, not just what it does.
Built-in audit trail: You track AI-assisted decisions without extra tooling.
Measurable AI effectiveness: Teams can see which skills produce the fewest corrections.
Smarter future agents: Every agent inherits your project's accumulated knowledge instead of starting blind.
Faster code reviews: Reviewers read explicit context instead of guessing.

Context 🧠

AI agents don't share memory across sessions by default.

Every new task starts with a blank slate unless you give them written context.

AGENTS.md, SKILL.md, and WORKFLOW.md files solve this for project-level knowledge.

Pull requests solve it for change-level knowledge.

Think of a PR as a commit message for your AI reasoning.

A commit message records what changed.

An AI-trace PR description records how and why the AI reached that solution.

Teams that treat PRs as AI learning artifacts get better over time: each merged change makes the next AI session smarter.

This matches the continuous improvement loop from lean manufacturing (kaizen) applied to AI-assisted development.

You inspect every unit of work, identify waste (bad prompts, missing rules), and standardize the improvement (new skill, updated workflow).

Prompt Reference 📝

Bad PR Description:

Fixed the payment bug

[x] Fixed the null check
[x] Tests pass


 - if ($payment !== null) {
 -     $payment->process();
 - }
 + if ($payment !== null && $payment->isValid()) {
 +     $payment->process();
 + }

// No AI context. No prompt. No record of what failed first.
// The next agent reads this diff and learns nothing.

Good PR Description:

Fixed PaymentProcessor null check with Null Object pattern

**AI Context**
Tool    : Claude Code (claude-sonnet-4-20250514)
Skill   : /skills/php-clean-code.md §3
Rules   : /AGENTS.md#error-handling
Workflow: /workflows/refactor-feature.md
Prompt  : "Refactor PaymentProcessor using the
           Null Object pattern instead of null
           checks. Follow AGENTS.md conventions."

**What the AI tried first**
Inline null guard. Rejected — violates AGENTS.md
rule on conditionals.

**Manual correction applied**
Renamed NullPayment to NullPaymentMethod to match
domain vocabulary. Added to AGENTS.md#naming.

payment.ts
 - if ($payment !== null) {
 -     $payment->process();
 - }
 + $payment->process();

AGENTS.md

  ## error-handling
  - Don't use null checks inline.
  - Use guard clauses only at system boundaries.
 + - Replace null checks with Null Object pattern.
 + - Null Objects live in /src/NullObjects/.
 + - Null Object class names follow NullX convention.


skills/clean-code.md

## 3 Null Handling
- - Avoid null returns when possible.
+ - Never check for null inside domain logic.
+ - Inject a Null Object instead.
+ - Example: NullPaymentMethod implements PaymentMethod.
+ - Prompt: "Replace null check in X with a Null Object
+    that implements the same interface."

Considerations ⚠️

Keep the AI Context section short.

Three to five lines are enough.

You document it, not transcribe it.

Sensitive business logic in prompts needs the same care as any other PR content.

Your repo's access policy applies.

Not every PR needs full AI tracing.

A one-line typo fix doesn't.

A non-trivial refactor or new feature always does.

Don't paste the entire conversation.

Extract the signal: the decisive prompt and the first failed attempt.

AGENTS.md updates from PR traces should go through review like any other code change.

Type 📝

[X] Semi-Automatic

Limitations ⚠️

This practice requires team discipline.
One developer skipping it breaks the knowledge chain.
AI tools that don't expose prompt history make extraction harder.
Use tools that let you copy the context.
Large monorepos with many SKILL.md files need a naming convention so PR references stay unambiguous.
You can't retroactively trace PRs merged before you adopted this practice.
Start from today and move forward.

Tags 🏷️

Standards

Level 🔋

[X] Intermediate

Related Tips 🔗

Maxi Contieri

Jan 27

AI Coding Tip 004 - Use Modular Skills

#ai #webdev #programming #beginners

Comments

4 min read

Maxi Contieri

Feb 13

AI Coding Tip 006 - Review Every Line Before Commit

#ai #programming #development #softwaredevelopment

Comments 1

7 min read

Maxi Contieri

Mar 18

AI Coding Tip 011 - Initialize Agents.md

#ai #programming

Comments

3 min read

Maxi Contieri

Apr 7

AI Coding Tip 014 - Use Nested AGENTS.md Files

#ai #webdev #programming #productivity

Comments

4 min read

Conclusion 🏁

Pull requests aren't just code snapshots.

They're the cheapest knowledge transfer mechanism your team has.

When you log the prompt, the active skills, the rules, and the first failure alongside the final diff, you turn every merged change into a lesson.

Your AGENTS.md improves.

Your SKILL.md library grows.

Your next AI session starts smarter than the last.

Stop letting AI reasoning disappear at merge time. 🧠

More Information ℹ️

GitHub: Writing good pull request descriptions

Conventional Commits: Structured commit messages

ADR: Architecture Decision Records as a model for AI traces

Google's AI-assisted code review research

Trunk-based development and AI-assisted PRs

Also Known As 🎭

AI-Aware-Pull-Requests
Prompt-Traced Code Reviews
AI-Knowledge-Commits

Disclaimer 📢

The views expressed here are my own.

I am a human who writes as best as possible for other humans.

I use AI proofreading tools to improve some texts.

I welcome constructive criticism and dialogue.

I shape these insights through 30 years in the software industry, 25 years of teaching, and writing over 500 articles and a book.

This article is part of the AI Coding Tip series.

Maxi Contieri

Jan 21

AI Coding Tips

#webdev #ai #programming #beginners

Comments

1 min read

AI Coding Tip 015 - Force the AI to Obey You

Maxi Contieri — Tue, 14 Apr 2026 11:00:00 +0000

Don't let your most important instructions drown in context noise

TL;DR: Bury critical rules and AI models ignore them. Use explicit markers to force compliance.

Common Mistake ❌

You write a long skill file with dozens of rules.

You bury the most critical ones somewhere in the middle, polluting the context.

The lazy AI follows the easy instructions and skips the hard ones.

You never notice until the output is already wrong, and you are frustrated.

Problems Addressed 😔

AI models suffer from attention dilution. The longer the context, the weaker the focus on any single rule
Critical constraints buried mid-file get ignored silently
The AI doesn't tell you it skipped a rule. It just doesn't follow it
Large skills consume so much context that late instructions compete with early ones
You waste time debugging outputs instead of trusting your skill
Re-running the same prompt gives inconsistent results

How to Do It 🛠️

Start with a MANDATORY block. Put your non-negotiable rules at the very top, before any context or explanation
Use explicit severity markers. Prefix rules with MANDATORY, CRITICAL, or IMPORTANT in ALL CAPS
Apply progressive disclosure. Start with the strictest rules, then reveal nuance and context only after anchoring the constraints
Repeat key rules at the end. Models give extra weight to what they read first and last (primacy and recency effect)
Split large skills into focused modules. One file per concern beats one giant file every time
Use structural separators. Use ---, ===, or explicit headers like ## RULES (READ FIRST) to visually isolate critical sections
Prefer numbered rules over prose. "Rule 1: Never do X" is harder to skip than "you should avoid doing X in most cases"
Write a short TL;DR at the top. A one-line summary of the skill's purpose acts as a memory anchor for the whole file
Add a violation example. Show explicitly what breaking the rule looks like so the model has a concrete anti-pattern to avoid
Test adversarially. Craft prompts designed to make the AI break your rules, then fix the skill until they hold
Add lots of good and bad examples. Create another file in the skill directory with good and bad examples. Tell the LLM to document the bad examples when it doesn't understand you
Use Local Rules. Put the most critical rules in a separate file and reference it in the skill

Benefits 🎯

Your most critical constraints survive long context windows
You get consistent outputs across multiple runs
You spend less time debugging skill failures
Other developers understand which rules are non-negotiable at a glance
You can safely grow your skill file without burying old rules
You get more confident and less frustrated

Context 🧠

AI models don't read skill files the way humans do.

They process tokens sequentially, but attention is not uniform.

Rules near the start and end of a prompt get more weight.

Rules in the middle of a 200-line skill file get the least.

This matters most when your skill file grows beyond ~50 lines.

The LLM loads all your previous messages (in and out) and the system prompt.

Small skills rarely have this problem.

Large, multi-purpose skills suffer from it constantly.

Progressive disclosure is a UX concept you can apply to prompts.

You reveal information in layers: constraints first, then context, then examples, then edge cases.

The AI commits to the constraints before it encounters exceptions.

Prompt Reference 📝

Bad Prompt 🚫

You are a code reviewer. 
Here is a lot of context about the project, 
the team, the coding standards, 
the history of the codebase, 
the preferred libraries...

[100 lines later]
...and by the way, never suggest using any deprecated APIs.
Also, always respond in Swedish.

The language rule and the API rule are buried.

The AI will forget them or apply them inconsistently.

Good Prompt 👉

## MANDATORY RULES (apply to every response):
1. CRITICAL: Always respond in Swedish. No exceptions.
2. CRITICAL: Never suggest deprecated APIs.
3. MANDATORY: Keep suggestions under 5 lines each.

---

## Context (read after committing to the rules above)
You are a code reviewer for a legacy PHP project...
[context follows]

---

## Reminder (same rules repeated):
- Language: Swedish only
- No deprecated APIs
- Max 5 lines per suggestion

The AI reads the rules first, then the context.

The repetition at the end reinforces both constraints.

Considerations ⚠️

MANDATORY and CRITICAL only work if you use them sparingly. When everything is critical, nothing is.
Don't repeat every rule. Repeat only the ones that are genuinely catastrophic to break.
Progressive disclosure doesn't mean hiding context. It means ordering context from most-constrained to least.
Some models respond better to numbered rules than to prose. Test both formats with your target model.
Very long skill files are often a design smell. Ask yourself if you can split one skill into two focused ones.

Type 📝

[X] Semi-Automatic

Limitations ⚠️

This tip applies to models with large context windows (8k+ tokens). Smaller context limits change the tradeoff entirely.
You can't fully compensate for a poorly structured skill by just adding CRITICAL markers. Clean structure matters more.
Repetition helps, but too much repetition wastes tokens and can confuse the model with contradictory-looking rewrites.
This doesn't replace testing. Always validate your skill with adversarial prompts before trusting it in production.

Tags 🏷️

Context Window

Level 🔋

[X] Intermediate

Related Tips 🔗

Maxi Contieri

Mar 31

AI Coding Tip 013 - Use Progressive Disclosure

#ai #coding #llm #productivity

Comments 1

5 min read

Maxi Contieri

Apr 7

AI Coding Tip 014 - Use Nested AGENTS.md Files

#ai #webdev #programming #productivity

Comments

4 min read

Keep your skill files focused on a single concern
Use TL;DR anchors at the top of every long prompt
Test your prompts adversarially before shipping
Prefer explicit rules to implicit conventions in skills
Split skills by domain, not by file size

Conclusion 🏁

A long skill file doesn't enforce itself.

You need to structure it so the AI can't ignore the parts that matter.

Put critical rules first.

Mark them explicitly.

Repeat the non-negotiables at the end.

When you apply progressive disclosure, you guide the AI the same way you guide a human reader.

From constraints to context, not the other way around.

More Information ℹ️

Lost in the Middle: How Language Models Use Long Contexts
Attention Is All You Need (original Transformer paper)
Anthropic Prompt Engineering Guide
OpenAI Best Practices for Prompt Engineering

Large Language Models as Instruction Followers
Structured Prompting for Reliable LLM Outputs
Context Length and Model Attention Patterns

Also Known As 🎭

Instruction-anchoring
Constraint-first-prompting
Rule-salience-in-prompts
Attention-aware-skill-design

Disclaimer 📢

The views expressed here are my own.

I am a human who writes as best as possible for other humans.

I use AI proofreading tools to improve some texts.

I welcome constructive criticism and dialogue.

I shape these insights through 30 years in the software industry, 25 years of teaching, and writing over 500 articles and a book.

This article is part of the AI Coding Tip series.

Maxi Contieri

Jan 21

AI Coding Tips

#webdev #ai #programming #beginners

Comments

1 min read

Code Smell 319 - Hardcoded Stateless Properties

Maxi Contieri — Fri, 10 Apr 2026 11:00:00 +0000

Don't turn collaborators into permanent roommates

TL;DR: You should avoid storing stateless utility classes as instance variables initialized with new.

Problems 😔

Hardcoded dependencies
Testing difficulties
High coupling
Hidden side effects
Rigid design
Misleading intent
Premature Optimization
Stack clutter

Solutions 😃

Use dependency injection
Pass as parameter
Use static methods
Inline the logic
Use local variables
Inline object creation

Refactorings ⚙️

Maxi Contieri

Mar 9 '25

Refactoring 024 - Replace Global Variables with Dependency Injection

#webdev #programming #javascript #beginners

Comments

7 min read

Maxi Contieri

Jul 11 '25

Refactoring 030 - Inline Attributes

#webdev #programming #javascript #beginners

Comments

7 min read

Maxi Contieri

Jul 4 '22

Refactoring 007 - Extract Class

#webdev #beginners #javascript #tutorial

Comments

1 min read

Context 💬

Hardcoding a stateless class in the constructor creates permanent coupling.

Even if the class is cheap to instantiate, you lose the ability to swap it.

Stateless objects shouldn't be part of the object's internal state.

You confuse readers by making a tool look essential to the object's identity.

It makes testing harder because you can't mock the hardcoded dependency.

Sample Code 💻

Wrong 🚫

class UserProcessor {
  private provider: MockDataProvider;

  constructor() {
    // You hardcode the dependency here.
    // This makes the class harder to test.
    this.provider = new MockDataProvider();
  }

  process(data: any) {
    return this.provider.format(data);
  }
}

Right 👉

interface DataProvider {
  format(data: any): any;
}

class UserProcessor {
  // You inject the dependency via constructor.
  // Now you can swap it or mock it easily.
  constructor(private readonly provider: DataProvider) {}

  process(data: any) {
    return this.provider.format(data);
  }
}

// Simpler but coupled
 class UserProcessor {
    constructor() {
      // Empty
    }

    process(data: any) {
      return new MockDataProvider().format(data);
    }
  }

Detection 🔍

Look for the new keyword inside constructors.

Watch for private properties instantiated directly in the constructor rather than passed as parameters.

Most linters flag this pattern automatically when you create instances and assign them to private fields.

Tags 🏷️

Premature Optimization

Level 🔋

[X] Beginner

Why the Bijection Is Important 🗺️

Software should mimic a MAPPER of the real world.

In reality, a worker might use a tool to complete a task.

The tool is not a permanent physical attachment to the worker.

When you refactor to use dependency injection, you respect the bijection by treating collaborators as external entities, not internal state.

This keeps your simulation flexible and accurate.

AI Generation 🤖

AI generators frequently create this smell.

They often suggest code that just works by instancing dependencies directly in the constructor to save time.

AI Detection 🧲

AI can easily detect this smell without explicit instructions.

When you show AI a class with new keywords in the constructor, it recognizes the pattern as hardcoded coupling.

AI identifies that stateless utility classes should be injected rather than instantiated internally.

The detection is straightforward because the pattern is syntactically obvious and semantically harmful.

Try Them! 🛠

Remember: AI Assistants make lots of mistakes

Suggested Prompt: remove the cached attribute

Without Proper Instructions	With Specific Instructions
ChatGPT	ChatGPT
Claude	Claude
Perplexity	Perplexity
Copilot	Copilot
You	You
Gemini	Gemini
DeepSeek	DeepSeek
Meta AI	Meta AI
Grok	Grok
Qwen	Qwen

Conclusion 🏁

Storing stateless dependencies as instance variables makes your code rigid.

When you inject these dependencies instead, you improve testability and keep your objects focused on their true purpose.

Relations 👩‍❤️‍💋‍👨

Maxi Contieri

Oct 25 '20

Code Smell 06 - Too Clever Programmer

#codenewbie #tutorial #beginners

Comments 7

2 min read

Maxi Contieri

Nov 8 '20

Code Smell 20 - Premature Optimization

#oop #developing #coding #codesmell

Comments

2 min read

More Information 📕

Maxi Contieri

Feb 6 '21

Coupling: The one and only software design problem

#webdev #programming #oop #tutorial

Comments 2

5 min read

Disclaimer 📘

Code Smells are my opinion.

Credits 🙏

Photo by Possessed Photography on Unsplash

Coupling is the enemy of change

Rich Hickey

Maxi Contieri

Dec 28 '20

Software Engineering Great Quotes

#codenewbie #programming #quotes #software

Comments

75 min read

This article is part of the CodeSmell Series.

Maxi Contieri

May 21 '21

How to Find the Stinky parts of your Code

#codenewbie #tutorial #codequality #beginners

Comments

14 min read

AI Coding Tip 014 - Use Nested AGENTS.md Files

Maxi Contieri — Tue, 07 Apr 2026 11:00:00 +0000

Context is precious. Don't waste it.

TL;DR: Split your AGENTS.md into layered files so your AI loads only the rules that matter for the code you touch.

Common Mistake ❌

You put a single massive AGENTS.md , CLAUDE.md , GEMINI.md at your project root and cram everything into it.

Framework rules, database patterns, front-end conventions, and continuous integration configuration—all loaded at once.

Your AI reads rules that have nothing to do with what you're actually working on.

This wastes context and weakens the guidance that matters.

Problems Addressed 😔

Your AI follows rules meant for other parts of the codebase
Irrelevant context crowds out the rules you actually need
Updating one big file can break guidance for unrelated areas
Teammates get confused by your personal preferences

How to Do It 🛠️

Create a root AGENTS.md with global rules: coding standards, commit format, architecture overview, and general gotchas
Add subdirectory AGENTS.md files in each major area (model/, tests/, api/) with area-specific rules
Create AGENTS.local.md for personal preferences and add it to .gitignore
Keep files short, opinionated, and actionable—three bullets over three paragraphs
Trust the loading system: most tools load root files at startup and subdirectory files only when you touch files there

FermiCalculator/
├── AGENTS.md       ← loaded at startup (always) with general
│                   rules
├── model/
│   └── AGENTS.md   ← loaded when you make changes to your
│                   model/, model conventions
├── tests/
│   └── AGENTS.md   ← loaded when you change your tests/,
│                   mocking rules
├── ui/
│   └── AGENTS.md   ← loaded when you make changes to ui/,
│                   UI code standards
└── api/
│   └── AGENTS.md   ← loaded when you make changes to api/,
│                   OpenApi formatting
└── database/
│   └── AGENTS.md   ← loaded when you make changes to the
│                   persistence/ DDL Rules

Benefits 🎯

The AI reads only rules relevant to what you're working on
You reduce context waste in every session
Each team area owns its own guidance independently
Personal preferences stay personal — they don't pollute shared files
Smaller files are easier to review and maintain

Context 🧠

AI coding assistants load context files to understand your project.

Tools like Claude Code, Cursor, and Copilot support instruction files (AGENTS.md, CLAUDE.md, .cursorrules).

When you put everything in one file, your assistant can't filter what's relevant.

The layered approach works like good software: separation of concerns.

The root file sets foundations.

Subdirectory files add specifics.

Local files hold personal quirks.

This helps any project with multiple distinct areas—monorepos benefit most.

Remember, you always need to manage your context wisely.

Prompt Reference 📝

Bad Prompt:

Here are all the conventions for my project:

[pastes 200 lines of mixed rules for backend, frontend, 
mobile, and CI]

Now help me fix this React component.

Good Prompt:

I'm working in UI/. My AGENTS.md for this area says: 

use functional components, no class components,

Tailwind only for styling, 

test with React Testing Library.

Help me fix this component.

Considerations ⚠️

Not all tools support lazy loading of subdirectory files—check your tool first
A short bad AGENTS.md hurts less than a long one. Vague rules get ignored or misapplied
Consider adding AGENTS.md when you create new subdirectories
Review your root file regularly. Outdated rules mislead more than good guidance. See Outdated Documentation
Avoid AI external comments

Type 📝

[X] Semi-Automatic

Limitations ⚠️

Works best with tools that support hierarchical context loading (Claude Code, Cursor, some Copilot)
Single-file projects don't need this structure
You still need good rules—the hierarchy only helps if the content is solid
AGENTS.local.md support varies by tool; check your documentation

Tags 🏷️

Standards

Level 🔋

[X] Intermediate

Related Tips 🔗

Maxi Contieri

Feb 4

AI Coding Tip 005 - Keep Context Fresh

#webdev #programming #ai #tutorial

Comments

4 min read

Use examples in your AGENTS.md, not just descriptions
Version-control your AGENTS.md alongside your code

Conclusion 🏁

You don't need one perfect AGENTS.md.

You need the right rules in the right place.

Split context by area, keep files tight, and let tools load only what's relevant.

Your AI works better with less noise.

More Information ℹ️

Stop Using Claude Code as a ChatBot

Claude Code CLAUDE.md documentation

Cursor Rules documentation

GitHub Copilot custom instructions

OpenAI ChatGPT custom instructions

Aider conventions file

Cody context and instructions

Monorepo tooling with Nx

Context window management in LLMs

Prompt engineering guide

Also Known As 🎭

Hierarchical context files
Layered instructions
Nested AI rules
Scoped assistant configuration

Tools 🧰

Claude Code (CLAUDE.md)
Cursor (.cursorrules / .cursor/rules)
GitHub Copilot (.github/copilot-instructions.md)
Aider (CONVENTIONS.md)
Continue.dev (.continuerc.json)

Disclaimer 📢

The views expressed here are my own.

I am a human who writes as best as possible for other humans.

I use AI proofreading tools to improve some texts.

I welcome constructive criticism and dialogue.

I shape these insights through 30 years in the software industry, 25 years of teaching, and writing over 500 articles and a book.

This article is part of the AI Coding Tip series.

Maxi Contieri

Jan 21

AI Coding Tips

#webdev #ai #programming #beginners

Comments

1 min read

AI Coding Tip 013 - Use Progressive Disclosure

Maxi Contieri — Tue, 31 Mar 2026 11:00:00 +0000

Structure your skills so the AI loads only the files it needs. Split complexity across modular files and use keywords to trigger conditional loading.

TL;DR: You reduce token usage when you trigger conditional loading instead of loading all files at once.

Common Mistake ❌

You load a complex skill with 20 associated files into your context window all at once.

Your context window fills up immediately.

You waste tokens on irrelevant file content and cases that don't match what you're asking.

The AI gets lost in noise and disobeys your commands.

You can't ask follow-up questions because there's no space left and hallucinations happen.

Problems Addressed 😔

You waste tokens loading skill files you don't need
The AI reads case definitions that don't apply to your input
Context window fills up before you can iterate or ask follow-ups
Response time slows down because the AI is overwhelmed
You lose precision when the AI picks the wrong file or rule

How to Do It 🛠️

Split your skill into multiple files (one per concern)
Write a smart description with clear conditional triggers
Define keywords that trigger file loading
Create conditional rules: "If input contains X, load file Y"
Include response templates so the AI knows how to structure answers
Nest file references only when needed (e.g., array.md loads nested.md only for nested arrays)
Test your keywords to ensure the AI picks them up correctly

Benefits 🎯

The AI loads only the files it needs.

You save 90% of tokens on irrelevant skill content.

Response times stay fast even with complex skills.

Your context window stays clean for follow-up questions.

Each request is precise because the AI only sees rules that matter.

Context 🧠

Agentic skills can be massive.

A syntax validator might have files for declarations, arrays, nested arrays, function calls, and scripts.

If you load all of them, the AI wastes tokens reading rules that don't apply.

Progressive disclosure in skills works by defining keywords that trigger file loading.

When you write "DECLARE 123", the skill recognizes the DECLARE keyword and loads declaration.md.

The AI only reads what matters.

You write descriptions using "What," "When," or "How" patterns.

You create conditional rules in your main skill file.

You include response templates so answers stay consistent.

The AI requests what it needs using keywords, so you don't have to guess.

How Skills Work 🔄

Skills implement progressive disclosure at three stages:

Discovery: At startup, agents load only the name and description of each available skill.

Just enough information to know when a skill might be relevant.

No full instructions, no referenced files, no code—only the metadata.

Activation: When a task matches a skill's description, the agent reads the full SKILL.md instructions into context.

Now the agent has the complete instructions and knows what to do.

Still no unnecessary files or code loaded yet.

Execution: The agent follows the instructions, optionally loading referenced files or executing bundled code as needed.

Only when the AI detects it needs something does it load that file or run that script.

This approach keeps agents fast while giving them access to more context when they actually need it.

Each step is triggered by actual need, not preloaded upfront.

Prompt Reference 📝

Bad Prompt:

# SKILL.md (15,000 tokens - Monolithic)

Validates DECLARE, arrays, nested arrays,
function calls, loops, all in one file.

DECLARE Rules:
- First char uppercase
- Can't start with number

Array Rules:
- Use square brackets [item]
- Examples: [foo], [bar]

Function Call Rules:
- Parentheses required: func()
- Parameters separated by commas

Loop Rules:
- FOR, WHILE, DO keywords
- Body must be indented

When you ask "Is DECLARE 123 valid?" the AI loads all 15,000 tokens covering every rule.

Context window fills up fast.

Good Prompt:

# SKILL.md (800 tokens - Modular)

Validates foo syntax: DECLARE, arrays,
nested arrays, function calls, loops.

Rules:
- DECLARE detected → load declaration.md
- [ detected → load array.md
- ( detected → load function-call.md

Template: [input] valid?
[YES/NO]. Reason: [rule].

declaration.md (1,200 tokens):

First character must be uppercase.
Cannot start with number.
Examples: DECLARE x, DECLARE foo

array.md (1,500 tokens):

Must use brackets: [item]
References nested-array.md for [x]
Examples: [foo], [bar], [123]

When you ask "Is DECLARE 123 valid?" the AI loads only SKILL.md (800) + declaration.md (1,200) = 2,000 tokens.

Context stays clean for follow-up questions.

Considerations ⚠️

Define your keywords upfront so the AI recognizes them consistently.

Each file should handle one concern (declarations, arrays, etc.).

Don't create too many nested references or the loading chain becomes confusing.

Test your keyword patterns to make sure the AI recognizes them.

If your skill includes scripts, review them carefully.

Scripts can create security risks if they run without review.

Type 📝

[X] Semi-Automatic

Limitations ⚠️

Progressive disclosure works best when keywords are distinctive.

Generic words like "function" might trigger too often and load the wrong file.

Deeply nested file structures (3+ levels) are confusing to maintain.

External scripts need security review before you share skills from online repositories.

Keywords must be clear or the AI loads files unpredictably.

Tags 🏷️

Standards

Level 🔋

[X] Intermediate

Related Tips 🔗

Maxi Contieri

Jan 6

AI Coding Tip 001 - Commit Before Prompt

#ai #development #coding #webdev

Comments

3 min read

Maxi Contieri

Feb 4

AI Coding Tip 005 - Keep Context Fresh

#webdev #programming #ai #tutorial

Comments

4 min read

Maxi Contieri

Mar 3

AI Coding Tip 009 - Compact Your Context

#webdev #ai #programming #tutorial

Comments 1

4 min read

Conclusion 🏁

Progressive disclosure in skills means splitting files by concern and using keywords to trigger conditional loading.

You define what the AI needs to see, not dump everything.

Include templates so responses stay consistent.

When you get good at this pattern, even complex skills stay fast, efficient, and focused. 🎯

More Information ℹ️

Agent skills progressive disclosure

Claude Token Counting Guide

Context Windows and Token Limits

Prompt Engineering Patterns

UX Progressive Disclosure

Information Architecture Best Practices

Cognitive Load Theory

Efficient Prompt Design

API Cost Optimization

Code Context Patterns

Also Known As 🎭

Layered context disclosure
Just-in-time information architecture
Context-on-demand

Tools 🧰

Windsurf with progressive disclosure
GitHub Copilot with skills
Claude with custom skills
VS Code Copilot Chat
Agentic frameworks
Token counter tools

Disclaimer 📢

The views expressed here are my own.

I am a human who writes as best as possible for other humans.

I use AI proofreading tools to improve some texts.

I welcome constructive criticism and dialogue.

I shape these insights through 30 years in the software industry, 25 years of teaching, and writing over 500 articles and a book.

This article is part of the AI Coding Tip series.

Maxi Contieri

Jan 21

AI Coding Tips

#webdev #ai #programming #beginners

Comments

1 min read

AI Coding Tip 012 - Understand All Your Code

Maxi Contieri — Mon, 23 Mar 2026 15:25:54 +0000

You own the code. Own and understand what it does.

TL;DR: Never ship AI-generated code you don't understand — ask until you do.

Common Mistake ❌

You ask an AI agent to implement a feature.

It returns 200 lines of code.

You run the tests. They pass. You commit and push.

You think you are the best 'agentic-coder' in the world.

But you never read the code.

Three weeks later, a security issue appears in production.

The AI introduced subtle bugs you could have caught in two minutes.

You didn't catch it because you never looked.

You're accountable but don't understand what the code does, and you can't explain it to others.

There are many fancy video tutorials on using agents without reviewing the code.

Remember, there must always be a human in the loop.

Problems Addressed 😔

You lose control of your own codebase.
You can't debug code you don't understand.
You ship vulnerabilities without knowing they exist.
You can't explain your own code in a code review.
You build a dependency on AI that makes you a worse engineer over time.
You take legal and professional responsibility for code you never vetted.

Maxi Contieri

Nov 4 '25

Code Smell 313 - Workslop Code

#webdev #programming #ai #web3

Comments

7 min read

How to Do It 🛠️

Read every code line the AI generates or modifies before you accept it.
Ask the AI to explain any part you don't understand.
Ask follow-up questions until the explanation is clear to you.
Identify the assumptions the AI made and verify them.
Check edge cases the AI might have missed.
Refactor and polish any part that you would not have written that way yourself.
Make the code yours before you commit it.

Benefits 🎯

You stay as the author of your codebase, not just a curator of AI output.
You catch defects before they reach production.
You learn from what the AI generates.
You build trust with your team because you can explain your code.
You make better prompts over time because you understand what went wrong.

Context 🧠

AI agents are fast. That speed creates pressure.

You feel like slowing down to read breaks the momentum.

It doesn't. It saves you.

The AI doesn't know your system. It doesn't know your constraints.

It doesn't know what happened last quarter when you made a similar change.

You do. That context is irreplaceable.

When you skip reading, you hand off judgment to a tool that has no judgment. You outsource the one thing only you can do.

Asking questions is not a sign of weakness.

It is how you stay in control.

The AI won't judge you for asking.

It will give you a better answer.

Prompt Reference 📝

Bad Prompt:

Implement user authentication,

add it to the project,

commit and push to the main branch.

*This prompt gives the AI full authority over a critical system. *

*You get a blob of code with no checkpoint for understanding.*

Good Prompt:

Implement a login function using JWT.

Use RS256 signing.

After you write it, ask me questions about each step.

I'd like to understand what you did on every line of code

*This prompt sets expectations.*

*You get code AND an explanation.*

*You know what to verify.*