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 🛠️

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

2. Paste or link the key prompt: You don't need the full conversation.

   Include the decisive prompt that unlocked the solution.

3. List the active configuration files: Name every SKILL.md, AGENTS.md section, RULES file, or WORKFLOW.md that shaped the output.

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

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

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

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

8. Tag the PR with an "ai-assisted" label: This lets you filter and audit AI-assisted changes later for quality review.

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

10. Ask the LLM to update what it learned: Write a final prompt for the AI to update its own knowledge.

Benefits 🎯

1. Reusable learning units: Every PR becomes a lesson agents can read and reuse.

2. Living AGENTS.md: Your rules file grows richer with each merged change instead of staying a static document nobody updates.

3. Shorter feedback loop: You compress the gap between a good prompt and a reusable skill.

4. Clearer onboarding: New developers understand why code looks the way it does, not just what it does.

5. Built-in audit trail: You track AI-assisted decisions without extra tooling.

6. Measurable AI effectiveness: Teams can see which skills produce the fewest corrections.

7. Smarter future agents: Every agent inherits your project's accumulated knowledge instead of starting blind.

8. 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
the 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 🔗

https://maxicontieri.substack.com/p/ai-coding-tip-004-use-modular-skills

https://maxicontieri.substack.com/p/ai-coding-tip-006-review-every-line

https://maxicontieri.substack.com/p/ai-coding-tip-011-initialize-agentsmd

https://maxicontieri.substack.com/p/ai-coding-tip-014-use-nested-agentsmd

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.

https://maxicontieri.substack.com/p/ai-coding-tips

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 🛠️

1. Start with a MANDATORY block. Put your non-negotiable rules at the very top, before any context or explanation

2. Use explicit severity markers. Prefix rules with MANDATORY, CRITICAL, or IMPORTANT in ALL CAPS

3. Apply progressive disclosure. Start with the strictest rules, then reveal nuance and context only after anchoring the constraints

4. Repeat key rules at the end. Models give extra weight to what they read first and last (primacy and recency effect)

5. Split large skills into focused modules. One file per concern beats one giant file every time

6. Use structural separators. Use ---, ===, or explicit headers like ## RULES (READ FIRST) to visually isolate critical sections

7. Prefer numbered rules over prose. "Rule 1: Never do X" is harder to skip than "you should avoid doing X in most cases"

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

9. Add a violation example. Show explicitly what breaking the rule looks like so the model has a concrete anti-pattern to avoid

10. Test adversarially. Craft prompts designed to make the AI break your rules, then fix the skill until they hold

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

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 🔗

https://maxicontieri.substack.com/p/ai-coding-tip-013-use-progressive

• Tip: Keep your skill files focused on a single concern

• Tip: Use TL;DR anchors at the top of every long prompt

• Tip: Test your prompts adversarially before shipping

• Tip: Prefer explicit rules over implicit conventions in skills

• Tip: 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 ℹ️

https://arxiv.org/abs/2307.03172

Attention Is All You Need (original Transformer paper)

https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/overview

OpenAI Best Practices for Prompt Engineering

https://learnprompting.org/docs/intermediate/review

Progressive Disclosure (UX principle)

https://arxiv.org/abs/2109.01652

Prompt Injection and Instruction Hierarchy

https://arxiv.org/abs/2212.10535

Context Length and Model Attention Patterns

Also Known As 🎭

• Instruction anchoring

• Constraint-first prompting

• Rule salience in prompts

• Attention-aware skill design

Tools 🧰

• Claude.ai (skill/system prompt editor)

• Cursor rules (.cursorrules file)

• GitHub Copilot instructions (.github/copilot-instructions.md)

• Continue.dev (custom system prompts)

• LangChain PromptTemplate

• OpenAI Playground (system message editor)

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.

https://maxicontieri.substack.com/p/ai-coding-tips

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 😃

1. Use dependency injection

2. Pass as parameter

3. Use static methods

4. Inline the logic

5. Use local variables

6. Inline object creation

Refactorings ⚙️

https://maxicontieri.substack.com/p/refactoring-024-replace-global-variables

https://maxicontieri.substack.com/p/refactoring-030-inline-attributes

https://maxicontieri.substack.com/p/refactoring-007-extract-class-5b0b5960d0e7

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 without dependency injection.

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

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 👩‍❤️‍💋‍👨

https://maxicontieri.substack.com/p/code-smell-06-too-clever-programmer-bffec35daf0b

https://maxicontieri.substack.com/p/code-smell-20-premature-optimization-60409b7f90ec

Disclaimer 📘

Code Smells are my opinion.

Credits 🙏

Photo by Possessed Photography on Unsplash

Coupling is the enemy of change

Rich Hickey

https://maxicontieri.substack.com/p/software-engineering-great-quotes-3af63cea6782

This article is part of the CodeSmell Series.

https://maxicontieri.substack.com/p/how-to-find-the-stinky-parts-of-your-code-fa8df47fc39c

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 at your project root and cram everything into it.

Framework rules, database patterns, frontend 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 🛠️

1. Create a root AGENTS.md with global rules: coding standards, commit format, architecture overview, and general gotchas

2. Add subdirectory AGENTS.md files in each major area (model/, tests/, api/) with area-specific rules

3. Create AGENTS.local.md for personal preferences and add it to .gitignore

4. Keep files short, opinionated, and actionable—three bullets over three paragraphs

5. 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 🔗

https://maxicontieri.substack.com/p/ai-coding-tip-005-keep-context-fresh

• 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

Continue.dev context files

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.

https://maxicontieri.substack.com/p/ai-coding-tips

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 🛠️

1. Split your skill into multiple files (one per concern)
2. Write a smart description with clear conditional triggers
3. Define keywords that trigger file loading
4. Create conditional rules: "If input contains X, load file Y"
5. Include response templates so the AI knows how to structure answers
6. Nest file references only when needed (e.g., array.md loads nested.md only for nested arrays)
7. 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 a 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 a 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 a 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 🔗
<p><a class="embed-card" href="https://maxicontieri.substack.com/p/ai-coding-tip-001-commit-before-prompt">https://maxicontieri.substack.com/p/ai-coding-tip-001-commit-before-prompt</a></p>
<p><a class="embed-card" href="https://maxicontieri.substack.com/p/ai-coding-tip-005-keep-context-fresh">https://maxicontieri.substack.com/p/ai-coding-tip-005-keep-context-fresh</a></p>
<p><a class="embed-card" href="https://maxicontieri.substack.com/p/ai-coding-tip-009-compact-your-context">https://maxicontieri.substack.com/p/ai-coding-tip-009-compact-your-context</a></p>

# 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](https://agentskills.io/what-are-skills#how-skills-work)

[Claude Token Counting Guide](https://docs.anthropic.com/en/docs/build-a-bot)

[Context Windows and Token Limits](https://docs.anthropic.com/en/docs/about-claude/models/overview)

[Prompt Engineering Patterns](https://docs.anthropic.com/en/docs/build-a-bot)

[UX Progressive Disclosure](https://en.wikipedia.org/wiki/Progressive_disclosure)

[Information Architecture Best Practices](https://www.nngroup.com/articles/ia-basics/)

[Cognitive Load Theory](https://www.nngroup.com/articles/cognitive-load-estimation/)

[Efficient Prompt Design](https://platform.openai.com/docs/guides/prompt-engineering)

[API Cost Optimization](https://docs.anthropic.com/en/docs/about-claude/models/overview)

[Code Context Patterns](https://arxiv.org/abs/2304.08134)
<p><a class="embed-card" href="https://www.youtube.com/watch?v=DQHFow2NoQc">https://www.youtube.com/watch?v=DQHFow2NoQc</a></p>
<p><a class="embed-card" href="https://www.youtube.com/watch?v=hTKhLgRcAys">https://www.youtube.com/watch?v=hTKhLgRcAys</a></p>

# Also Known As 🎭

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

# Tools 🧰

- Windsurf with [progressive disclosure](https://docs.windsurf.com/windsurf/cascade/skills)
- 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.
<p><a class="embed-card" href="https://maxicontieri.substack.com/p/ai-coding-tips">https://maxicontieri.substack.com/p/ai-coding-tips</a></p>

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 lots of fancy video tutorials about using agents without reviewing 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.

[https://maxicontieri.substack.com/p/code-smell-313-workslop-code]

How to Do It 🛠️

1. Read every code line the AI generates or modifies before you accept it.
2. Ask the AI to explain any part you don't understand.
3. Ask follow-up questions until the explanation is clear to you.
4. Identify the assumptions the AI made and verify them.
5. Check edge cases the AI might have missed.
6. Refactor and polish any part that you would not have written that way yourself.
7. 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 🔗

https://maxicontieri.substack.com/p/ai-coding-tip-006-review-every-line

• 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 ℹ️

https://pragprog.com/titles/tpp20/the-pragmatic-programmer-20th-anniversary-edition/

https://owasp.org/www-project-top-ten/

https://google.github.io/eng-practices/review/

https://martinfowler.com/bliki/CodeSmell.html

https://arxiv.org/abs/2211.03622

https://www.acm.org/code-of-ethics

https://stackoverflow.blog/2023/04/17/how-ai-changes-code-ownership/

https://www.ieee.org/education/standards/index.html

https://cwe.mitre.org/

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.

https://maxicontieri.substack.com/p/ai-coding-tips

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 🛠️

1. Open your terminal in your project root directory.
2. Type /init if you use Claude Code or OpenCode.
3. Review the generated CLAUDE.md or AGENTS.md file.
4. Add specific "landmines" or things the AI can't see in the code.
5. Save the file, review the commit diffs, and start your next coding task.
6. 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 🔗

https://maxicontieri.substack.com/p/ai-coding-tip-006-review-every-line

• 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 ℹ️

https://opencode.ai/docs/rules/

https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview%23claudemd-guide

https://docs.cursor.com/context/rules-for-ai

https://docs.windsurf.com/windsurf/cascade/memories

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.

https://maxicontieri.substack.com/p/ai-coding-tips

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 commiting 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 🏷️

#CLI-Agents #Productivity #Codebase-Context #Automation

Level 🔋

[X] Intermediate

Related Tips 🔗

https://maxicontieri.substack.com/p/ai-coding-tip-003-force-read-only

https://maxicontieri.substack.com/p/ai-coding-tip-006-review-every-line

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 ℹ️

https://www.firecrawl.dev/blog/why-clis-are-better-for-agents

Aider - AI Pair Programming in your Terminal

https://code.claude.com/docs/en/overview

https://www.builder.io/blog/opencode-vs-claude-code

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.

https://maxicontieri.substack.com/p/ai-coding-tips

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 functions that do not exist.

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 🛠️

1. Restart often: You can start a new chat once you finish a sub-task.

2. Request a State Summary: Before you close a conversation, ask the AI to summarize the current decisions and plan.

3. Add Human Checkpoints: After the summary, confirm you are still on track.

4. Use Markdown Docs: Keep a small context.md file with your current stack and rules.

5. Prune the Logs: You should only paste the relevant 5 lines of a stack trace instead of the whole irrelevant 200-line output.

6. Divide and conquer Break large tasks into smaller ones, invoking their own skills with local tokens.

7. Divide the responsibility: A General doesn't need to know what every soldier is doing.

8. Create and persist as Skill: After you have taught the AI, you should refactor the knowledge.

9. Keep and Eye on the Context Size: Most tools have visual indicators of the window consumption.

10. Use Local Persistence: Some tools allow sharing memory among agents and 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 on 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.

Considerations ⚠️

You must ensure you don't purge essential context.

If you prune too much, the AI might suggest libraries that conflict with your current setup.

Review the compacted information.

Type 📝

[X] Semi-Automatic

Limitations ⚠️

You can use this tip manually in any chat interface.

If you use advanced agents like Claude Code or Cursor, they might handle some of this automatically, but manual pruning is still more reliable.

Tags 🏷️

• Context

Level 🔋

[X] Intermediate

Related Tips 🔗

https://maximilianocontieri.com/ai-coding-tip-004-use-modular-skills

https://maximilianocontieri.com/ai-coding-tip-005-keep-context-fresh

AI Coding Tip 010 - Create Skill from Conversation

Conclusion 🏁

You are the curator of the AI's memory.

If you let the context rot, the code will rot too. Keep it clean and compact. 🧹

More Information ℹ️

https://arxiv.org/abs/2307.03172

https://llmlingua.com/

https://www.cursor.com/blog/context

https://www.ibm.com/topics/ai-hallucinations

https://www.promptingguide.ai/

https://openai.com/blog/custom-instructions-for-chatgpt/

https://docs.anthropic.com/claude/docs/long-context-tips

Also Known As 🎭

• Context Pruning

• Token Management

• Prompt Compression

Tools 🧰

• Claude Code

• Cursor

• Windsurf

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.

https://maximilianocontieri.com/ai-coding-tips

TL;DR: Use AI to understand requirements and build a shared mental model while you write the code.

Common Mistake ❌

You jump directly to code generation with a vague, wishful prompt.

The AI seems to understand your specific business logic, but is condescending with you.

The problem creates a spaghetti mess that is difficult to maintain later.

The AI is not a magic button for lazy people. It is a senior pair programmer and a learning companion.

You follow the Spec-Driven Development trend and work in a taylorist cascading way failing into analysis paralysis and unrealistic plans.

Problems Addressed 😔

Hallucinations: The AI guesses details when you don't provide specific context.

Technical Debt: You build complex systems that collapse under logical errors and don't simulate the real-world MAPPER.

Context Fragmentation: The AI loses track of your goals in long sessions.

Logic Drift: The code "works". Yet it doesn't solve the actual problem.

How to Do It 🛠️

Ask the AI to interview you.

You state the high-level idea and have the AI ask questions to uncover edge cases.

Work together in learning mode. Dave Farley tells us to be experts at learning.

Draft a spec.md file. You and the AI collaborate on a document that defines the architecture, data models, and goals.

Use the Plan Mode.

Keep the AI in a read-only environment to explore your codebase and verify the plan as you execute it.

Plan as you go with the goal in mind without making assumptions about a rigid roadmap.

Always validate the bijection against the real-world requirements.

Turn the live spec into a simple checklist of atomic implementation steps.

The backlog will grow and shrink as you learn the domain. It is a live artifact.

Set up a persistent context while you learn.

Create a .md file to store project rules that the AI cannot guess.

Benefits 🎯

You learn about the domain faster because the AI can serve as an encyclopedic mentor.

You stay proudly accountable for the architecture.

You eliminate boilerplate while maintaining system stability.

You close the Human 30% gap by focusing on system coordination.

Context 🧠

These tools are high-velocity coders, but they are very innocent.

They perform best when you instruct with a clear mission and modular instructions.

This "waterfall in 15 minutes" way favors you and the AI to be on the same page before you trigger the first code diff.

Prompt Reference 📝

Bad Prompt:

Build me a task management app with React and Node.

Create a behavior specification and a Gantt project

Good Prompt:

You are a Senior Software Engineer. I want to build a task app.

Ask me 10 clarifying questions about the architecture, security, 
and data model. 

After I answer, help me draft a spec.md.

Let's build it together with TDD and contract tests.

Considerations ⚠️

AI can write bugs with complete conviction.

You must review every change.

Type 📝

[X] Semi-Automatic

Tags 🏷️

• Complexity

Level 🔋

[X] Intermediate

Related Tips 🔗

Use CLAUDE.md for project memory.

Set up MCP servers for live documentation.

Run parallel agents for large refactors.

Conclusion 🏁

You should invest 15 minutes in planning with the AI instead of rushing. It will save you hours of debugging.

Use the copilot to improve your design with your approval, and let it handle the hard accidental typing.

More Information ℹ️

• Start with a clear path (specs before code)

• Break work into small, iterative chunks

• Provide extensive context and guidance

• Choose the right model (and use multiple when needed)

• Leverage AI coding across the lifecycle

• Keep a human in the loop - verify, test, and review everything

• Commit often and use version control as a safety net. Never commit code you can’t explain.

• Customize the AI’s behavior with rules and examples

• Embrace testing and automation as force multipliers

• Continuously learn and adapt (AI amplifies your skills)

Also Known As 🎭

Spec-Driven Development

Waterfall in 15 Minutes

Vibe Coding with Discipline

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.

https://maximilianocontieri.com/ai-coding-tips

TL;DR: Treat AI agent skills like dangerous executable code and read the instructions carefully.

Common Mistake ❌

You install community skills for your AI assistant based on popularity or download counts.

You trust "proactive" agents when they ask you to run "setup" commands or install "AuthTool" prerequisites.

You grab exciting skills from public registries and install them right away.

You skip code reviews or scans because the docs look clean.

You are lazy and careless.

Problems Addressed 😔

Information stealers raid your SSH keys, browser cookies, and .env files.

Supply chain attacks exploit naming confusion (ClawdBot vs. MoltBot vs. OpenClaw).

Typosquatting pushes you into installing malicious packages like clawhubcli.

Your adversaries invoke Remote Code Execution (RCE) through unvalidated WebSocket connections.

How to Do It 🛠️

Run your AI agent inside a dedicated isolated Virtual Machine or Docker container.

This isolation prevents the agent from accessing your primary filesystem.

Review the SKILL.md and source code of every new skill.

You can spot hidden curl commands or Base64-encoded strings that reach out to malicious IPs like 91.92.242.30.

Use security scanners like Clawdex or Koi Security's tool.

The tools check your skills against a database of known malicious signatures.

Bind your agent's gateway strictly to 127.0.0.1. When you bind to 0.0.0.0, you expose your administrative dashboard to the public internet.

Limit the agent's permissions to read-only for sensitive directories.

This is also excellent for reasoning and planning

You can prevent the agent from modifying system files or stealing your keychain.

Benefits 🎯

You protect your production API keys and cloud credentials, protecting the secrets in your code.

You stop lateral movement inside your corporate network.

You reduce the risk of identity theft through session hijacking.

You avoid Package Hallucination

Context 🧠

AI Agents like OpenClaw have deep administrative system access. They can run shell commands and manage files.

Attackers now flood registries with "skills" that look like helpful tools for YouTube, Solana, or Google Workspace.

When you install these, you broaden your attack surface and grant an attacker a direct shell on your machine.

Prompt Reference 📝

Bad prompt 🚫

Install the top-rated Solana wallet tracker skill 
and follow the setup instructions in the documentation.

Good prompt 👉

Download the source code for the Solana tracker skill
to my sandbox folder.

Wait until y review it line by line

Good Prompt: "Download the source code for the Solana tracker skill to my sandbox folder.

Let's analyze the scripts together for any external network calls before we install it."

Considerations ⚠️

OpenClaw often stores secrets in plaintext .env files.

If you grant an agent access to your terminal, any malicious skill can read these secrets and exfiltrate them to a webhook in seconds.

Type 📝

[X] Semi-Automatic

Limitations ⚠️

Use this strategy when you host "agentic" AI platforms like OpenClaw or MoltBot locally.

This tip doesn't replace traditional endpoint protection but adds a necessary layer for AI-specific supply chain risks.

Tags 🏷️

• Security

Level 🔋

[X] Intermediate

Related Tips 🔗

Isolate LLM tool execution with Kernel-enforced sandboxes.

Audit prompt injection risks in web-scraping agents.

Encrypt local configuration files for AI assistants.

Conclusion 🏁

Your AI assistant is a powerful tool, but it can also become a high-impact control point for attackers.

When you verify every skill, understand it, and isolate the runtime, you keep the "keys to your kingdom" safe. 🛡️

More Information ℹ️

Also Known As 🎭

Agentic Supply Chain Poisoning

ClickFix AI Attacks

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.

TL;DR: If you can't explain all your code, don't commit it.

Common Mistake ❌

You prompt and paste AI-generated code directly into your project without thinking twice.

You trust the AI without verification and create workslop that someone else will have to clean up later.

You assume the code works because it looks correct (or complicated enough to impress anyone).

You skip manual review when the AI assistant generates large blocks because, well, it's a lot of code.

You treat AI output as production-ready code and ship it without a second thought.

If you're making code reviews, you get tired of large pull requests (probably generated by AI) that feel like reviewing a novel.

Let's be honest: AI isn't accountable for your mistakes—you are.

Problems Addressed 😔

• Security vulnerabilities and flaws: AI generates code with Not sanitized inputs SQL injection, XSS, Packages Hallucination, or hardcoded credentials
• Logic errors: The AI misunderstands your requirements and solves the wrong problem
• Technical debt: Generated code uses outdated patterns or creates maintenance nightmares
• Lost accountability: You cannot explain code you didn't review
• Hidden defects: Issues that appear in production cost 30-100x more to fix
• Knowledge gaps: You miss learning opportunities when you blindly accept solutions
• Team friction: Your reviewers waste time catching issues you should have found
• Productivity Paradox: AI shifts the bottleneck from writing to integration
• Lack of Trust: The team's trust erodes when unowned code causes failures
• Noisier Code: AI-authored PRs contained 1.7x more issues than human-only PRs.

How to Do It 🛠️

1. Ask the AI to generate the code you need using English language
2. Read every single line the AI produced, understand it, and challenge it if necessary
3. Check that the solution matches your actual requirements
4. Verify the code handles edge cases and errors
5. Look for security issues (injection, auth, data exposure)
6. Test the code locally with real scenarios
7. Run your linters, prettifiers and security scanners
8. Remove any debug code or comments you don't need
9. Refactor the code to match your team's style
10. Add or update tests for the new functionality (ask the AI for help)
11. Write a clear commit message explaining what changed
12. Only then commit the code
13. You are not going to lose your job (by now)

Benefits 🎯

You catch defects before they reach production.

You understand the code you commit.

You maintain accountability for your changes.

You learn from your copilot's approach and become a better developer in the process.

You build personal accountability.

You build better human team collaboration and trust.

You prevent security breaches like the Moltbook incident.

You avoid long-term maintenance costs.

You keep your reputation and accountability intact.

You're a professional who shows respect for your human code reviewers.

You are not disposable.

Context 🧠

AI assistants like GitHub Copilot, ChatGPT, and Claude help you code faster.

These tools generate code from natural language prompts and vibe coding.

AI models are probabilistic, not logical.

They predict the next token based on patterns.

When you work on complex systems, the AI might miss a specific edge case that only a human knows.

Manual review is the only way to close the gap between "code that looks good" and "code that is correct."

The AI doesn't understand your business logic or the real world bijection between your MAPPER and your model.

The AI cannot know your security requirements (unless you are explicit or execute a skill).

The AI cannot test the code against your specific environment.

You remain responsible for every line in your codebase.

Production defects from unreviewed AI code cost companies millions.

Code review catches many security risks that automated tools miss.

Your organization holds you accountable for the code you commit.

This applies whether you write code manually or use AI assistance.

Prompt Reference 📝

Bad Prompts ❌

class DatabaseManager:
    _instance = None # Singleton Anti Pattern
    def __new__(cls):
        if cls._instance is None:
            cls._instance = super().__new__(cls)
        return cls._instance
    def get_data(self, id):
        return eval(f"SELECT * FROM users WHERE id={id}") 
        # SQL injection!

    ## 741 more cryptic lines

Good Prompts ✅

from typing import Optional
import sqlite3

class DatabaseManager:
  def __init__(self, db_path: str):
    self.db_path = db_path

  def get_user(self, user_id: int) -> Optional[dict]:
    try:
      with sqlite3.connect(self.db_path) as conn:
        conn.row_factory = sqlite3.Row
        cursor = conn.cursor()
        cursor.execute("SELECT * FROM users WHERE id = ?", (user_id,))
        row = cursor.fetchone()
        return dict(row) if row else None
    except sqlite3.Error as e:
        print(f"Database error: {e}")
        return None

db = DatabaseManager("app.db")
user = db.get_user(123)

Considerations ⚠️

You cannot blame the AI when defects appear in production.

The human is accountable, not the AI.

AI-generated code might violate your company's licensing policies.

The AI might use deprecated libraries or outdated patterns.

Generated code might not follow your team's conventions.

You need to understand the code to maintain it later.

Other developers will review your AI-assisted code just like any other.

Some AI models train on public repositories and might leak patterns.

Type 📝

[X] Semi-Automatic

Limitations ⚠️

You should use this tip for every code change. You should not skip it even for "simple" refactors.

Tags 🏷️

-Readability

Level 🔋

[X] Beginner

Related Tips 🔗

• Self-Review Your Code Before Requesting Peer Review
• Write Tests for AI-Generated Functions
• Document AI-Assisted Code Decisions
• Use Static Analysis on Generated Code
• Understand Before You Commit

Conclusion 🏁

AI assistants accelerate your coding speed.

You still own every line you commit.

Manual review and code inspections catch what automated tools miss.

Before AI code generators became mainstream, a very good practice was to make a self review of the code before requesting a peer review.

You learn more when you question the AI's choices and understand the 'why' behind them.

Your reputation depends on code quality, not how fast you can churn out code.

Take responsibility for the code you ship—your name is on it.

Review everything. Commit nothing blindly. Your future self will thank you. 🔍

Be incremental, make very small commits and keep your content fresh.

More Information ℹ️

Also Known As 🎭

• Human-in-the-Loop Code Review
• AI Code Verification
• AI-Assisted Development Accountability
• LLM Output Validation
• Copilot Code Inspection

Tools 🧰

• SonarQube (static analysis)
• Snyk (security scanning)
• ESLint / Pylint (linters)
• GitLab / GitHub (code review platforms)
• Semgrep (pattern-based scanning)
• CodeRabbit / AI-assisted code reviews

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.

TL;DR: Wrap primitive collections into dedicated objects to ensure type safety and encapsulate business logic.

Problems Addressed 😔

• Type safety violations
• Logic duplication
• Primitive obsession
• Weak encapsulation
• Strong coupling avoiding collection type changes
• Hidden business rules

Related Code Smells 💨

Context 💬

You find yourself passing around generic lists, arrays, or dictionaries as if they were just anemic "bags of data." like DTOs or Data Clumps.

These primitive structures are convenient to iterate.

But they are also anonymous and lack a voice in the business domain.

When you use a raw array to represent a group of specific entities—like ActiveSubscribers, PendingInvoices, or ValidationErrors—you are essentially forcing every part of your system to re-learn how to handle that data, leading to scattered logic and "primitive obsession."

When you reify the collection, you improve the model and create technical implementation into a first-class citizen of your domain model.

This doesn't just provide a home for validation and filtering; it makes the invisible concepts in your business requirements visible in your code.

Steps 👣

1. Create a new class to represent the specific collection.

2. Define a private collection property within this class using the appropriate collection type.

3. Implement a constructor that accepts only elements of the required type.

4. Add type-hinted methods to add, remove, or retrieve elements.

5. Move collection-specific logic (like sorting or filtering) from the outside into this new class.

Sample Code 💻

Before 🚨

<?

/** @var User[] $users */
// this is a static declaration used by many IDEs but not the compiler
// Like many comments it is useless, and possible outdated

function notifyUsers(array $users) {
    foreach ($users as $user) {
        // You have no guarantee $user is actually a User object
        // The comment above is 
        // just a hint for the IDE/Static Analysis
        $user->sendNotification();
    }
}

$users = [new User('Anatoli Bugorski'), new Product('Laser')]; 
// This array is anemic and lacks runtime type enforcement
// There's a Product in the collection and will show a fatal error
// unless it can understand #sendNotification() method

notifyUsers($users);

After 👉

<? 

class UserDirectory {
// 1. Create a new class to represent the specific collection
// This is a real world concept reified  
// 2. Define a private property
private array $elements = [];

    // 3. Implement a constructor that accepts only User types
    public function __construct(User ...$users) {
        $this->elements = $users;
    }

    // 4. Add type-hinted methods to add elements
    public function add(User $user): void {
        $this->elements[] = $user;
    }

    // 5. Move collection-specific logic inside
    public function notifyAll(): void {
        foreach ($this->elements as $user) {
            $user->sendNotification();
        }
    }
}

Type 📝

[X] Manual

Safety 🛡️

This refactoring is very safe.

You create a new structure and gradually migrate references.

Since you add strict type hints in the new class, the compiler engine catches any incompatible data at runtime, preventing silent failures.

Why is the Code Better? ✨

You transform a generic, "dumb" array into a specialized object that understands its own rules. You stop repeating validation logic every time you handle the list. The code becomes self-documenting because the class name explicitly tells you what the collection contains.

How Does it Improve the Bijection? 🗺️

In the real world, a "List of Users" or a "Staff Directory" is a distinct concept with specific behaviors.

An anonymous array is a technical implementation detail, not a real-world entity.

By reifying the collection, you create a one-to-one correspondence between the business concept and your code.

Limitations ⚠️

You might encounter slight performance overhead when dealing with millions of objects compared to raw arrays.

For most business applications, the safety gains far outweigh the millisecond costs and prevents you from being a premature optimizator.

Remember to avoid hollow Specialized Business collections that don't exist in the real world.

Many languages support typed collections:

• C# achieves typed collections through reified generics in the CLR, preserving type information at runtime for types like List.

• C++ achieves typed collections through templates like blueprints instantiated at compile time for each concrete type.

• Clojure achieves typed collections through optional static typing libraries such as core.typed.

• Dart achieves typed collections through reified generics with runtime type checks in sound null safety mode.

• Elixir achieves typed collections through typespecs analyzed by Dialyzer for static verification.

• Go achieves typed collections through parametric generics introduced in Go 1.18 with type parameters and constraints.

• Haskell achieves typed collections through parametric polymorphism and type classes resolved at compile time.

• Java achieves typed collections through generics with type erasure, enforcing type constraints at compile time on classes like List and Map.

• JavaScript achieves typed collections through TypeScript or Flow, which add static generic typing on top of the dynamic language (see below).

• Kotlin achieves typed collections through JVM generics with variance annotations and null-safety integrated into the type system.

• Objective-C achieves typed collections through lightweight generics that provide compile-time checks without full runtime enforcement.

• PHP achieves typed collections through docblock-based generics enforced by static analyzers like Psalm or PHPStan.

• Python achieves typed collections through type hints like list[T] and dict[K, V] checked by static analyzers such as mypy.

• Ruby achieves typed collections through external type systems like Sorbet or RBS layered on top of the dynamic runtime.

• Rust achieves typed collections through parametric types and trait bounds checked at compile time with monomorphization.

• Scala achieves typed collections through a powerful generic type system with variance and higher-kinded types.

• Swift achieves typed collections through generics with value semantics and protocol constraints.

• TypeScript achieves typed collections through structural typing and generics enforced at compile time and erased at runtime since JavaScript doesn't support them.

In all the above cases, reifying a real business object (if exists in the MAPPER) gives you a good extra abstraction layer.

Tags 🏷️

• Primitive Obsession

Level 🔋

[X] Intermediate

Related Refactorings 🔄

Refactor with AI 🤖

Ask your AI assistant to: "Identify where I am passing arrays of objects and suggest a Typed Collection class for them."

You can also provide the base class and ask: "Find a real business object and generate a boilerplate for a type-safe collection for this entity."

Credits 🙏

Image by Markéta Klimešová on Pixabay

Inspired by the "Collection Object" pattern in clean architecture and the ongoing quest for type safety in dynamic languages.

This article is part of the Refactoring Series.

TL;DR: Clear your chat history to keep your AI assistant sharp.

Common Mistake ❌

You keep a single chat window open for hours.

You switch from debugging a React component to writing a SQL query in the same thread.

The conversation flows, and the answers seems accurate enough.

But then something goes wrong.

The AI tries to use your old JavaScript context to help with your database schema.

This creates "context pollution."

The assistant gets confused by irrelevant data from previous tasks and starts to hallucinate.

Problems Addressed 😔

• Attention Dilution: The AI loses focus on your current task.
• Hallucinations: The model makes up subtle facts based on old, unrelated prompts .
• Token Waste: You pay for "noise" in your history.
• Illusion of Infinite Context: Today, context windows are huge. But you need to stay focused.
• Stale Styles: The AI keeps using old instructions you no longer need.
• Lack of Reliability: Response quality decreases as the context window fills up.

How to Do It 🛠️

1. You need to identify when a specific microtask is complete. (Like you would when coaching a new team member).
2. Click the "New Chat" button immediately and commit the partial solution.
3. If the behavior will be reused, You save it as a new skill (Like you would when coaching a new team member).
4. You provide a clear, isolated instruction for the new subject. (Like you would when coaching a new team member).
5. Place your most important instructions at the beginning or end
6. Limit your prompts to 1,500-4,000 tokens for best results. (Most tools show the content usage).

Benefits 🎯

• You get more accurate code suggestions.
• You reduce the risk of the AI repeating past errors.
• You save time and tokens because the AI responds faster with less noise.
• Response times stay fast
• You avoid cascading failures in complex workflows
• You force yourself to write down agents.md or skills.md for the next task

Context 🧠

Large Language Models use an "Attention" mechanism.

When you give them a massive history, they must decide which parts matter.

Just like a "God Object" in clean code, a "God Chat" violates the Single Responsibility Principle.

When you keep it fresh and hygienic, you ensure the AI's "working memory" stays pure.

Prompt Reference 📝

Bad Prompt (Continuing an old thread):

Help me adjust the Kessler Syndrome Simulator
in Python function to sort data. 

Also, can you review this JavaScript code? 

And I need some SQL queries tracking crashing satellites, too. 

Use camelCase. 

Actually, use snake_case instead. Make it functional. 

No, wait, use classes.

Change the CSS style to support
dark themes for the orbital pictures.

Good Prompt (In a fresh thread):

Sort the data from @kessler.py#L23.

Update the tests using the skill run-tests.

Considerations ⚠️

You must extract agents.md or skills.md before starting the new chat. (Like you would when coaching a new team member)

Use metacognition: Write down what you have learned. (Like you would when coaching a new team member)

The AI will not remember them across threads. (Like you would when coaching a new team member)

Type 📝

[X] Semi-Automatic

Level 🔋

[X] Intermediate

Related Tips 🔗

Place the most important instructions at the beginning or end

Conclusion 🏁

Fresh context leads to incrementalism and small solutions, Failing Fast.

When you start over, you win back the AI's full attention and fresh tokens.

Pro-Tip 1: This is not just a coding tip. If you use Agents or Assistants for any task, you should use this advice.

Pro-Tip 2: Humans need to sleep to consolidate what we have learned in the day; bots need to write down skills to start fresh a new day.

More Information ℹ️

Full Prompt Engineering Guide: Context Management

Avoiding AI Hallucinations

Anthropic Context Window Best Practices

Token Economy in Large Language Models

Also Known As 🎭

Context Reset

Thread Pruning

Session Hygiene

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.

TL;DR: Create small, specialized files with specific rules to keep your AI focused, accurate and preventing hallucinations.

Common Mistake ❌

You know the drill - you paste your entire project documentation or every coding rule into a single massive Readme.md or Agents.md

Then you expect the AI to somehow remember everything at once.

This overwhelms the model and leads to "hallucinations" or ignored instructions.

Problems Addressed 😔

• Long prompts consume the token limit quickly leading to context exhaustion.

• Large codebases overloaded with information for agents competing for the short attention span.

• The AI gets confused by rules and irrelevant noise that do not apply to your current task.

• Without specific templates, the AI generates non standardized code that doesn't follow your team's unique standards.

• The larger the context you use, the more likely the AI is to generate hallucinated code that doesn't solve your problem.

• Multistep workflows can confuse your next instruction.

How to Do It 🛠️

1. Find repetitive tasks you do very often, writing unit tests, creating React components, adding coverage, formatting Git commits.

2. Write a small Markdown file (a.k.a. skill) for each task. Keep it between 20 and 50 lines.

3. Follow the Agent Skills format.

4. Add a "trigger" at the top of the file. This tells the AI when to use these specific rules.

5. Include the technology (e.g., Python, PHP) and the goal of the skill in the metadata.

6. Give the files to your AI assistant (Claude, Cursor, or Windsurf) only when you need them restricting context to cheaper subagents (Junior AIS) invoking them from a more intelligent orchestrator.

7. Have many very short agents.md for specific tasks following the divide-and-conquer principle .

8. Put the relevant skills on agents.md.

Benefits 🎯

• Higher Accuracy: The AI focuses on a narrow set of rules.

• Save Tokens: You only send the context that matters for the specific file you edit.

• Portability: You can share these "skills" with your team across different AI tools.

Context 🧠

Modern AI models have a limited "attention span.".

When you dump too much information on them, the model literally loses track of the middle part of your prompt.

Breaking instructions into "skills" mimics how human experts actually work: they pull specific knowledge from their toolbox only when a specific problem comes up.

Skills.md is an open standardized format for packaging procedural knowledge that agents can use.

Originally developed by Anthropic and now adopted across multiple agent platforms.

A SKILL.md file contains instructions in a structured format with YAML.

The file also has progressive disclosure. Agents first see only the skill name and description, then load full instructions only when relevant (when the trigger is pulled).

Prompt Reference 📝

Bad prompt 🚫

Here are 50 pages of our company coding standards and business rules. 

Now, please write a simple function to calculate taxes.

Good prompt 👉

After you install your skill:

Good Prompt

Use the PHP-Clean-Code skill. 

Create a tax calculator function 
from the business specification taxes.md

Follow the 'Early Return' rule defined in that skill.

Considerations ⚠️

Using skills for small projects is an overkill.

If all your code fits comfortably in your context window, you're wasting time writing agents.md or skills.md files.

You also need to keep your skills updated regularly.

If your project architecture changes, your skill files must change too, or the AI will give you outdated advice.

Remember outdated documentation is much worse than no documentation at all.

Type 📝

[X] Semi-Automatic

Limitations ⚠️

Don't go crazy creating too many tiny skills.

If you have 100 skills for one project, you'll spend more time managing files than actually coding.

Group related rules into logical sets.

Tags 🏷️

#Architecture #Productivity #AI-Agents

Level 🔋

[X] Intermediate

Related Tips 🔗

• Keep a file like AGENTS.md for high-level project context.

• Create scripts to synchronize skills across different IDEs.

Conclusion 🏁

Modular skills turn a generic AI into a specialized engineer that knows exactly how you want your code written.

When you keep your instructions small, incremental and sharp, you get better results.

More Information ℹ️

Skills Repository

Agent Skills Format

Also Known As 🎭

• Instruction-Sets

• Prompt-Snippets

Tools 🧰

Most skills come in different flavors for:

• Cursor

• Windsurf

• GitHub Copilot

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.

TL;DR: Master the balance between AI speed and code with professional craftsmanship.

In this series, you will learn practical state-of-the-art advice to use AI to code.

https://maximilianocontieri.com/ai-coding-tip-001-commit-before-prompt

https://maximilianocontieri.com/ai-coding-tip-002-prompt-in-english

https://maximilianocontieri.com/ai-coding-tip-003-force-read-only-planning

https://maximilianocontieri.com/ai-coding-tip-004-use-modular-skills

https://maximilianocontieri.com/ai-coding-tip-005-keep-context-fresh

https://maximilianocontieri.com/ai-coding-tip-006-review-every-line-before-commit

https://maximilianocontieri.com/ai-coding-tip-007-avoid-malicious-skills

https://maximilianocontieri.com/ai-coding-tip-008-use-spec-driven-development-with-ai

https://maximilianocontieri.com/ai-coding-tip-009-compact-your-context

https://maximilianocontieri.com/ai-coding-tip-010-access-all-your-code

https://maximilianocontieri.com/ai-coding-tip-011-initialize-agents-md

https://maximilianocontieri.com/ai-coding-tip-012-understand-all-your-code

https://maximilianocontieri.com/ai-coding-tip-013-use-progressive-disclosure

https://maximilianocontieri.com/ai-coding-tip-014-use-nested-agents-md-files

... more coming soon!

TL;DR: Set your AI code assistant to read-only state before it touches your files.

Common Mistake ❌

You paste your failing call stack to your AI assistant without further instructions.

The copilot immediately begins modifying multiple source files.

It creates new issues because it doesn't understand your full architecture yet.

You spend the next hour undoing its messy changes.

Problems Addressed 😔

The AI modifies code that doesn't need changing.

The copilot starts typing before it reads the relevant functions.

The AI hallucinates when assuming a library exists without checking your package.json.

Large changes make code reviews and diffs a nightmare.

How to Do It 🛠️

Enter Plan Mode: Use "Plan Mode/Ask Mode" if your tool has it.

If your tool doesn't have such a mode, you can add a meta-prompt

Read this and wait for instructions / Do not change any files yet.

Ask the AI to read specific files and explain the logic there.

After that, ask for a step-by-step implementation plan for you to approve.

When you like the plan, tell the AI: "Now apply step 1."

Benefits 🎯

Better Accuracy: The AI reasons better when focusing only on the "why."

Full Control: You catch logic errors before they enter your codebase.

Lower Costs: You use fewer tokens when you avoid "trial and error" coding loops.

Clearer Mental Model: You understand the fix as well as the AI does.

Context 🧠

AI models prefer "doing" over "thinking" to feel helpful. This is called impulsive coding.

When you force it into a read-only phase, you are simulating a Senior Developer's workflow.

You deal with the Artificial Intelligence first as a consultant and later as a developer.

Prompt Reference 📝

Bad prompt 🚫

Fix the probabilistic predictor
in the Kessler Syndrome Monitor component 
using this stack dump.

Good prompt 👉

Read @Dashboard.tsx and @api.ts. Do not write code yet.
Analyze the stack dump.
When you find the problem, explain it to me.
Then, write a Markdown plan to fix it, restricted to the REST API.
[Activate Code Mode]
Create a failing test representing the error.
Apply the fix and run the tests until all are green

Considerations ⚠️

Some simple tasks do not need a plan.

You must actively read the plan the AI provides.

The AI might still hallucinate the plan, so verify it.

Type 📝

[X] Semi-Automatic

Limitations ⚠️

You can use this for refactoring and complex features.

You might find it too slow for simple CSS tweaks or typos.

Some AIs go the other way around, being too confirmative before changing anything. Be patient with them.

Tags 🏷️

• Complexity

Level 🔋

[X] Intermediate

Related Tips 🔗

Request small, atomic commits.

Conclusion 🏁

You save time when you think.

You must force the AI to be your architect before letting it be your builder.

This simple strategy prevents hours of debugging later. 🧠

More Information ℹ️

Also Known As 🎭

Read-Only Prompting

Consultant Mode

Tools 🧰

Disclaimer 📢

The views expressed here are my own.

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

I used 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.

TL;DR: When you prompt in English, you align with how AI learned code and spend fewer tokens>

Disclaimer: You might have noticed English is not my native language. This article targets people whose native language is different from English.

Common Mistake ❌

You write your prompt in your native language (other than English) for a technical task.

You ask for complex React hooks or SQL optimizations in Spanish, French, or Chinese.

You follow your train of thought in your native language.

You assume the AI processes these languages with the same technical depth as English.

You think modern AI handles all languages equally for technical tasks.

Problems Addressed 😔

The AI copilot misreads intent.

The AI mixes language and syntax.

The AI assistant generates weaker solutions.

Non-English languages use more tokens. You waste your context window.

The translation uses part of the available tokens in an intermediate prompt besides your instructions.

The AI might misinterpret technical terms that lack a direct translation.

For example: "Callback" becomes "Retrollamada" or "Rappel". The AI misunderstands your intent or wastes context tokens to disambiguate the instruction.

How to Do It 🛠️

1. Define the problem clearly.
2. Translate intent into simple English.
3. Use short sentences.
4. Keep business names in English to favor polymorphism.
5. Never mix languages inside one prompt (e.g., "Haz una función que fetchUser()…").

Benefits 🎯

You get more accurate code.

You fit more instructions into the same message.

You reduce hallucinations.

Context 🧠

Most AI coding models are trained mostly on English data.

English accounts for over 90% of AI training sets.

Most libraries and docs use English.

Benchmarks show higher accuracy with English prompts.

While models are polyglots, their reasoning paths for code work best in English.

Prompt Reference 📝

Bad prompt 🚫

Mejorá este código y hacelo más limpio

Good prompt 👉

Refactor this code and make it cleaner

Considerations ⚠️

You should avoid slang.

You should avoid long prompts.

You should avoid mixed languages.

Models seem to understand mixed languages, but it is not the best practice.

Some English terms vary by region. "Lorry" vs "truck". Stick to American English for programming terms.

Type 📝

[X] Semi-Automatic

You can ask your model to warn you if you use a different language, but this is overkill.

Limitations ⚠️

You can use other languages for explanations.

You should prefer English for code generation.
You must review the model reasoning anyway.

This tip applies to Large Language Models like GPT-4, Claude, or Gemini.

Smaller, local models might only understand English reliably.

Tags 🏷️

• Standards

Level 🔋

[x] Beginner

Related Tips 🔗

• Commit Before You Prompt

• Review Diffs, Not Code

Conclusion 🏁

Think of English as the language of the machine and your native tongue as the language of the human.

When you use both correctly, you create better software.

More Information ℹ️

Common Crawl Language Statistics

Also Known As 🎭

English-First Prompting

Language-Aligned Prompting

Disclaimer 📢

The views expressed here are my own.

I welcome constructive criticism and dialogue.

These insights are shaped by 30 years in the software industry, 25 years of teaching, and authoring over 500 articles and a book.

This article is part of the AI Coding Tip series.

TL;DR: Commit your code before asking an AI Assistant to change it.

Common Mistake ❌

Developers ask AI assistant to "refactor this function" or "add error handling" while they have uncommitted changes from their previous work session.

When the AI makes its changes, the git diff shows everything mixed together—their manual edits plus the AI's modifications.

If something breaks, they can't easily separate what they did from what the AI did and make a safe revert.

Problems Addressed 😔

• You mix your previous code changes with AI-generated code.

• You lose track of what you changed.

• You struggle to revert broken suggestions.

How to Do It 🛠️

1. Finish your manual task.

2. Run your tests to ensure everything passes.

3. Commit your work with a clear message like "feat: manual implementation of X".

4. You don't need to push your changes.

5. Send your prompt to the AI assistant.

6. Review the changes using your IDE's diff tool.

7. Accept or revert: Keep the changes if they look good, or run git reset --hard HEAD to instantly revert

8. Run the tests again to verify AI changes didn't break anything.

9. Commit AI changes separately with a message like refactor: AI-assisted improvement of X.

Benefits 🎯

Clear Diffing: You see the AI's "suggestions" in isolation.

Easy Revert: You can undo a bad AI hallucination instantly.

Context Control: You ensure the AI is working on your latest, stable logic.

Tests are always green: You are not breaking existing functionality.

Context 🧠

When you ask an AI to change your code, it might produce unexpected results.

It might delete a crucial logic gate or change a variable name across several files.

If you have uncommitted changes, you can't easily see what the AI did versus what you did manually.

When you commit first, you create a safety net.

You can use git diff to see exactly what the AI modified.

If the AI breaks your logic, you can revert to your clean state with one command.

You work in very small increments.

Some assistants are not very good at undoing their changes.

Prompt Reference 📝

+bash .git status # Check for uncommitted changes .git add . # Stage all changes .git commit -m "msg" # Commit with message .git diff # See AI's changes .git reset --hard HEAD # Revert AI changes .git log --oneline # View commit history +

Considerations ⚠️

This is only necessary if you work in write mode and your assistant is allowed to change the code.

Type 📝

[X] Semi-Automatic

You can enforce the rules of your assistant to check the repository status before making changes.

Limitations ⚠️

If your code is not under a source control system, you need to make this manually.

Tags 🏷️

• Complexity

Level 🔋

[X] Beginner

Related Tips 🔗

• Use TCR

• Use Vibe Test Driven Development

• Break Large Refactorings into smaller prompts

• Git Bisect for AI Changes**: Using git bisect to identify which AI-assisted commit introduced a defect

• Reverting Hallucinations

Conclusion 🏁

Treating AI as a pair programmer requires the same safety practices you'd use with a human collaborator: version control, code review, and testing.

When you commit before making a prompt, you create clear checkpoints that make AI-assisted development safer and more productive.

This simple habit transforms AI from a risky black box into a powerful tool you can experiment with confidently, knowing you can always return to a working state.

Commit early, commit often, and don't let AI touch uncommitted code.

More Information ℹ️

Tools 🧰

GIT is an industry standard, but you can apply this technique to any other version control software.

This article is part of the AI Coding Tip Series.

TL;DR: Don't waste time refactoring code that never changes; focus on frequently modified problem areas.

Problems 😔

• Wasted effort
• Wrong priorities
• Missed real issues
• Team productivity drop
• Resource misallocation
• False progress feeling

Solutions 😃

1. Analyze change frequency
2. Identify code hotspots
3. Use version control data
4. Focus on active areas
5. Measure code churn

Refactorings ⚙️

Context 💬

This is the anti code smell.

You come across ugly code with complex conditionals, long functions, and poor naming.

You remember Uncle Bob's motto of leaving the campsite better than when you found it.

Your refactoring instinct kicks in, and you spend days cleaning it up.

You feel productive, but you've wasted your time.

Bad code is only problematic when you need to change it.

Stable code, even when poorly written, doesn't hurt your productivity.

The real technical debt lies in code hotspots: areas that are both problematic and frequently modified.

Most codebases follow an extreme distribution where 5% of the code receives 90% of the changes.

Without analyzing version control history, you cannot identify which messy code actually matters.

You end up fixing the wrong things while the real problems remain untouched.

You need to address the technical debt by prioritizing code with poor quality and high change frequency.

Everything else is premature optimization disguised as craftsmanship.

Sample Code 📖

Wrong ❌

# This authentication module hasn't changed in 3 years
# It's deprecated and will be removed next quarter
# But you spend a week "improving" it

class LegacyAuthenticator:
    def authenticate(self, user, pwd):
        # Original messy code from 2019
        if user != None:
            if pwd != None:
                if len(pwd) > 5:
                    # Complex nested logic...
                    result = self.check_db(user, pwd)
                    if result == True:
                        return True
                    else:
                        return False
        return False

# After your "refactoring" (that nobody asked for):
class LegacyAuthenticator:
    def authenticate(self, user: str, pwd: str) -> bool:
        if not self._is_valid_input(user, pwd):
            return False
        return self._verify_credentials(user, pwd)

    def _is_valid_input(self, user: str, pwd: str) -> bool:
        return user and pwd and len(pwd) > 5

    def _verify_credentials(self, user: str, pwd: str) -> bool:
        return self.check_db(user, pwd)

# Meanwhile, the actively developed payment module
# (modified 47 times this month) remains a mess

Right 👉

# You analyze git history first:
# git log --format=format: --name-only | 
# grep -E '\.py$' | sort | uniq -c | sort -rn

# Results show PaymentProcessor changed 47 times this month
# And it does not have good enough coverage
# LegacyAuthenticator: 0 changes in 3 years

# Focus on the actual hotspot:
class PaymentProcessor:
    # This gets modified constantly and is hard to change
    # REFACTOR THIS FIRST
    def process_payment(self, amount, card, user, promo_code,
                       installments, currency, gateway):
        # 500 lines of tangled logic here
        # Changed 47 times this month
        # Every change takes 2+ days due to complexity
        pass

# Ignore stable legacy code
# But you can use IA to cover existing functionality
# With acceptance tests validated by a Human product owner

class LegacyAuthenticator:
    # Leave this ugly code alone
    # It works, it's stable, it's being deprecated
    # Your time is better spent elsewhere
    def authenticate(self, user, pwd):
        if user != None:
            if pwd != None:
                if len(pwd) > 5:
                    result = self.check_db(user, pwd)
                    if result == True:
                        return True
        return False

Detection 🔍

[X] Semi-Automatic

You can detect this smell by analyzing your version control history.

Track which files change most frequently and correlate that with code quality metrics.

Tools like CodeScene, git log analysis, or custom scripts can show your actual hotspots.

Track your defects to the code you change more often.

Exceptions 🛑

Sometimes you must refactor stable code when:

• New feature development requires adaptive changes
• Security vulnerabilities require fixes
• Regulatory compliance demands changes
• You're about to reactivate dormant features

The key is intentional decision-making based on real data, not assumptions.

Tags 🏷️

• Technical Debt

Level 🔋

[X] Intermediate

Why the Bijection Is Important 🗺️

While you build a MAPPER between your code and real-world behavior, you will notice some parts of your system are more actively changed than others.

Your bijection should reflect this reality.

When you refactor stable code, you break the correspondence between development effort and actual business value.

You treat all code equally in your mental model, but the real world shows extreme usage patterns: a small percentage of code handles the vast majority of changes.

You optimize for an imaginary world where all code matters equally.

AI Generation 🤖

Some code generators suggest refactorings without considering change frequency.

AI tools and linters analyze code statically and recommend improvements based on patterns alone and not usage.

They do not access your version control history to understand which improvements actually matter unless you explicitly tell them to do it.

AI might flag every long function or complex conditional, treating a dormant 500-line legacy method the same as an equally messy function you modify daily.

AI Detection 🧲

AI can help fix this smell if you provide proper context.

You need to give it version control data showing change frequencies. Without that information, AI will make the same mistakes humans do: recommending refactorings based purely on code structure.

Try Them! 🛠

Remember: AI Assistants make lots of mistakes

Suggested Prompt: Analyze this codebase's git history to identify files with high change frequency. Then review code quality metrics for those files. Recommend refactoring only the intersection of high-churn and low-quality code. Ignore stable low-quality code."

Conclusion 🏁

You cannot improve productivity by polishing code that never changes.

Technical debt only matters when it slows you down, which happens in code you actually modify.

Focus your refactoring efforts where they multiply your impact: the hotspots where poor quality meets frequent change.

Everything else is procrastination disguised as engineering excellence.

Let stable ugly code rest in peace.

Your human time is too valuable to waste on problems that don't exist.

Relations 👩‍❤️‍💋‍👨

More Information 📕

Disclaimer 📘

Code Smells are my opinion.

Credits 🙏

Photo by Viktor Keri on Unsplash

The first rule of optimization is: Don't do it. The second rule is: Don't do it yet.

Michael A. Jackson

This article is part of the CodeSmell Series.