Forem: Maxi Contieri

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.*

Considerations ⚠️

The AI can write completely wrong, confident-sounding code.
Passing tests doesn't mean you wrote correct logic.
The AI optimizes for plausible output, not correct output.
You are responsible for what you deploy, not the AI.
Some AI mistakes are subtle. You only catch them when you read carefully.

Type 📝

[X] Semi-Automatic

Limitations ⚠️

For very large generated files, break your review into sections.

Tags 🏷️

Readability

Level 🔋

[X] Beginner

Related Tips 🔗

Maxi Contieri

Feb 13

AI Coding Tip 006 - Review Every Line Before Commit

#ai #programming #development #softwaredevelopment

Comments 1

7 min read

AI Coding Tip - Ask the AI to Explain Its Own Code
AI Coding Tip - Use AI as a Pair Programmer, Not a Replacement

Conclusion 🏁

The AI writes fast. You think too slowly. That is not a flaw.

That is the division of labor that makes the combination work.

Speed without understanding is just faster mistakes.

Ask questions. Read the code. Own what you ship. 🏁

More Information ℹ️

The Pragmatic Programmer - Your Code, Your Responsibility

OWASP Top Ten - Common Security Risks in Code

Code Review Best Practices - Google Engineering

Martin Fowler - Code Smells

GitHub Copilot Security Research - Risks of AI Code

ACM Code of Ethics - Professional Responsibility

Stack Overflow Blog - How AI Changes Code Ownership

IEEE Software Engineering Standards

CWE - Common Weakness Enumeration

Also Known As 🎭

"Trust but verify."
"AI-generated code review."
"Responsible AI coding."
"Developer accountability"

Tools 🧰

Any AI coding assistant (GitHub Copilot, Claude, Cursor, Codeium)
Your language's linter and static analysis tool
Code review tools (GitHub PRs, GitLab MRs, Gerrit)

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 011 - Initialize Agents.md

Maxi Contieri — Wed, 18 Mar 2026 22:12:31 +0000

Summarize your architecture rules and give your AI a persistent memory

TL;DR: When you use the /init command, you create a context file that saves you from repeating instructions in every new session.

Common Mistake ❌

You waste time copying and pasting the same project rules into every new chat.

You forgot to tell the AI about your specific test commands.

When you start a fresh session, the AI loses all previous context about your coding style or architecture.

Create your own system prompts, persist them and keep an eye on them regularly.

Problems Addressed 😔

Repetitive and manual meta-prompting
Inconsistent code styles across sessions
High token usage from redundant instructions
AI hallucinations about build or test commands
Onboarding new projects

How to Do It 🛠️

Open your terminal in your project root directory.
Type /init if you use Claude Code or OpenCode.
Review the generated CLAUDE.md or AGENTS.md file.
Add specific "landmines" or things the AI can't see in the code.
Save the file, review the commit diffs, and start your next coding task.
You can do it again when you have new rules.

Benefits 🎯

When you initialize (/Init) your project, the AI reads all the repository immediately.

You get consistent results without extra effort.

You save tokens because you don't have to describe your stack every time.

Context 🧠

AI assistants start every session with a blank slate.

They don't remember what you told them yesterday.

Tools like Claude Code look for a specific file to understand your project.

When you provide this saved file, you close the gap between separate AI sessions.

Prompt Reference 📝

Bad Prompt:

Remember to use 2 spaces for indentation 
and always run 'npm run test:unit' 
before you finish the task.

Good Prompt:

git clone https://github.com/torvalds/linux.git

/Init

Considerations ⚠️

Keep the generated file short.

When you add too much text, the AI might get confused.

Don't include information that the AI can already find in your package.json or README.md.

Type 📝

[X] Semi-Automatic

Limitations ⚠️

You can only use this tip with AI tools that support persistent context files.

If you change your build tools, you can update the Markdown file manually, run /init again, or do both.

In Windsurf, there is no literal /init terminal command that automatically generates a configuration file, as Claude Code or OpenCode does.

Windsurf uses a more agentic approach where the AI (Cascade) either discovers your rules automatically or creates them when you ask.

Cascade, initialize a .windsurfrules file for this project. Include my tech stack, coding standards, and build commands.

Tags 🏷️

Standards

Level 🔋

[X] Beginner

Related Tips 🔗

AI Coding Tip 006 - Review Every Line Before Commit

Maxi Contieri ・ Feb 13

#ai #programming #development #softwaredevelopment

Use .cursorrules for local preferences
Create modular AGENTS.md files for monorepos
Keep your README.md updated for better AI indexing

Conclusion 🏁

When you use /init, you turn your AI from a temporary contributor into a permanent team member.

More Information ℹ️

OpenCode /Init

Claude Code: CLAUDE.md

.cursorrules in Cursor

Windsurf rules

Also Known As 🎭

Project-AI-Onboarding
Context-Bootstrapping

Tools 🧰

Claude Code
OpenCode
Cursor (via .cursorrules)

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.

AI Coding Tips

Maxi Contieri ・ Jan 21

#webdev #ai #programming #beginners

AI Coding Tip 010 - Access All Your Code

Maxi Contieri — Tue, 10 Mar 2026 18:52:48 +0000

Stop copying code chunks. Start letting AI agents work directly with your files.

TL;DR: Use terminal-based AI tools to give your assistant direct access to your local files and test suites.

Common Mistake ❌

You copy code snippets into a web browser chat like ChatGPT, Claude, or Grok.

You manually move code back and forth and give small chunks of code, filling up the context window.

You lose the context of your folder structure, relations among modules, and the whole architecture.

The AI often (wrongly) guesses your project layout and hallucinates.

When you do this, you get inconsistent code and outdated logic.

Problems Addressed 😔

Context Tax: Manual copying wastes your focus.
Hallucinations: The AI suggests libraries you don't actually have.
Isolated logic: The assistant doesn't know if your code even builds.
Manual effort: You have to run every test and fix every error yourself.

You're basically playing assistant to the AI, running around doing the busywork.

How to Do It 🛠️

Download a CLI or IDE tool like Claude Code, OpenCode, Windsurf, or similar, and let it access ALL your codebase.

(You'll need to check compliance, set up safeguards, and respect any NDAs).

Open your terminal and start an interactive session. Let the agent navigate through all your code.

Describe what you want to accomplish at a high level and delegate to the orchestrator agent.

Review the proposed plan in the terminal.

Approve the changes to update your local files.

Let the agent run your tests and fix failures automatically.

Benefits 🎯

Full project context through local AST and RAG indexing.

Self-healing code through automated shell feedback loops.

Multi-file edits in a single prompt.

Parallel development using multiple agent instances.

Iterative incremental learning and experimentation. Baby steps.

Context 🧠

We were all blown away when ChatGPT came out.

I wrote an article 2 days after its release, understanding it was a game-changer.

Even people like me who had been working with earlier GPT models.

Four years later, you still see many developers coding this way.

It works for small algorithms and functions, but falls apart for real software engineering.

Prompt Reference 📝

Bad Prompt

// Please fix the login bug in this snippet:

async function loginUser(email, password) {
  const url = 'https://api.penrosebrain.com/login';

  try {
    const response = await fetch(url, {
      method: 'PUT',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ email, password }),
    });

  } catch (error) {
    console.error('There was an error:', error.message);
    alert(error.message);
  }
}

Good Prompt

// opencode: "Create a failing text, fix the login bug, run tests, 
// Ensure it passes the new test and all the previous ones
// Create a Pull Request so I can review it

async function loginUser(email, password) {
  const url = 'https://api.penrosebrain.com/login';

  try {
    const response = await fetch(url, {
      method: 'PUT',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ email, password }),
    });

  } catch (error) {
    console.error('There was an error:', error.message);
    alert(error.message);
  }
}

Considerations ⚠️

CLI agents have a learning curve.

Always review all changes before committing them.

Use a sandbox environment if you run untrusted code.

Type 📝

[X] Semi-Automatic

Limitations ⚠️

Don't use this for tiny, one-off scripts.

Web chats work better for creative brainstorming or generating images.

High token usage in long sessions can drive up your API costs.

Tags 🏷️

Complexity

Level 🔋

[X] Intermediate

Related Tips 🔗

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

Connect external data using the Model Context Protocol (MCP).

Run local models if you need 100% privacy.

Conclusion 🏁

Move your AI assistant to the terminal.

You'll work faster and make fewer mistakes.

When you delegate the boring parts, you can focus on architecture and high-level design.

More Information ℹ️

Why CLIs Are Better for AI Coding Agents Than IDEs

How Cursor Actually Indexes Your Codebase

Aider - AI Pair Programming in your Terminal

Claude Code Overview

OpenCode vs Claude Code: Comparing AI Coding Agents

AI Coding Assistants for Large Codebases

Boosting My Developer Productivity with AI in 2025

OpenCode Documentation

Introducing Advanced Tool Use on the Claude Developer Platform

What is OpenCode? - AI Quick Reference

Also Known As 🎭

Agentic Coding

Terminal Agents

Autonomous Coding Loops

Tools 🧰

Claude Code, OpenCode, Aider, Codex CLI.

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 009 - Compact Your Context

Maxi Contieri — Tue, 03 Mar 2026 02:02:44 +0000

Stop the memory rot

TL;DR: You can keep your AI sharp by forcing it to summarize and prune what it remembers (a.k.a. compacting).

Common Mistake ❌

You keep a single, long conversation open for hours.

You feed the AI with every error log and every iteration of your code.

Eventually, the AI starts to ignore your early instructions or hallucinate # AI Coding Tip 009 - Compact Your Context

Stop the memory rot

TL;DR: You can keep your AI sharp by forcing it to summarize and prune what it remembers (a.k.a. compacting).

Common Mistake ❌

You keep a single, long conversation open for hours.

You feed the AI with every error log and every iteration of your code.

Eventually, the AI starts to ignore your early instructions or hallucinate nonexistent functions.

Problems Addressed 😔

Context Decay: The AI loses track of your original goals in the middle of a long chat.
Hallucinations: The model fills memory gaps with hallucinations or outdated logic.
Token Waste: You pay for the AI to re-read useless error logs from three hours ago.
Reduced Reasoning: A bloated context makes the AI less smart and more prone to simple mistakes.

How to Do It 🛠️

Restart often: You can start a new chat once you finish a sub-task.
Request a State Summary: Before you close a conversation, ask the AI to summarize the current decisions and plan.
Add Human Checkpoints: After the summary, confirm you are still on track.
Use Markdown Docs: Keep a small context.md file with your current stack and rules.
Prune the Logs: You should only paste the relevant 5 lines of a stack trace instead of the whole irrelevant 200-line output.
Divide and conquer: Break large tasks into smaller ones, invoking their own skills with local tokens and a fresh context.
Divide the responsibility: A General doesn't need to know what every soldier is doing on the battlefield.
Create and persist as Skill: After you have taught the AI, you should refactor the knowledge and business rules.
Keep an Eye on the Context Size: Most tools have visual indicators of the window consumption.
Use Local Persistence: Some tools allow sharing memory among agents and their sub-agents.

Benefits 🎯

You get more accurate code suggestions.
You avoid divergences
You follow the AI's train of thought.
You spend less time correcting the AI's hallucinations.
The AI follows your project constraints more strictly and keeps focused on your tasks

Context 🧠

Large Language Models have limited attention.

Long context windows are a trap.

Many modern models offer a very large context window.

In practice, they ignore a lot of them to your frustration.

Even with huge context windows, they prioritize and focus ob the beginning and the end of the prompt.

Prompt Reference 📝

Bad Prompt

Here is the 500-line log of my failed build. 

Also, remember that we changed the database schema 

Three hours ago in this chat.

Add the unit tests as I described above.

Now, refactor the whole component.

Good Prompt

I am starting a new session. Here is the current state: 

We use *PostgreSQL* with the 'Users' table schema [ID, Email]. 

The AuthService`interface is [login(), logout()]. 

Refactor the LoginComponent` to use these.