Forem: Maxi Contieri

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

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

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

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

Common Mistake ❌

You write clean code.

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

You write "Fix bug" as the description.

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

Not your teammates.

Not a new AI agent.

Not you.

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

Problems Addressed 😔

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

How to Do It 🛠️

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

Include the decisive prompt that unlocked the solution.

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

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

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

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

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

Benefits 🎯

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

Context 🧠

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

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

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

Pull requests solve it for change-level knowledge.

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

A commit message records what changed.

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

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

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

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

Prompt Reference 📝

Bad PR Description:

Fixed the payment bug

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


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

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

Good PR Description:

Fixed PaymentProcessor null check with Null Object pattern

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

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

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

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

AGENTS.md

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


skills/clean-code.md

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

Considerations ⚠️

Keep the AI Context section short.

Three to five lines are enough.

You document it, not transcribe it.

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

Your repo's access policy applies.

Not every PR needs full AI tracing.

A one-line typo fix doesn't.

A non-trivial refactor or new feature always does.

Don't paste the entire conversation.

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

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

Type 📝

[X] Semi-Automatic

Limitations ⚠️

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

Tags 🏷️

Standards

Level 🔋

[X] Intermediate

Related Tips 🔗

Maxi Contieri

Jan 27

AI Coding Tip 004 - Use Modular Skills

#ai #webdev #programming #beginners

Comments

4 min read

Maxi Contieri

Feb 13

AI Coding Tip 006 - Review Every Line Before Commit

#ai #programming #development #softwaredevelopment

Comments 1

7 min read

Maxi Contieri

Mar 18

AI Coding Tip 011 - Initialize Agents.md

#ai #programming

Comments

3 min read

Maxi Contieri

Apr 7

AI Coding Tip 014 - Use Nested AGENTS.md Files

#ai #webdev #programming #productivity

Comments

4 min read

Conclusion 🏁

Pull requests aren't just code snapshots.

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

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

Your AGENTS.md improves.

Your SKILL.md library grows.

Your next AI session starts smarter than the last.

Stop letting AI reasoning disappear at merge time. 🧠

More Information ℹ️

GitHub: Writing good pull request descriptions

Conventional Commits: Structured commit messages

ADR: Architecture Decision Records as a model for AI traces

Google's AI-assisted code review research

Trunk-based development and AI-assisted PRs

Also Known As 🎭

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

Disclaimer 📢

The views expressed here are my own.

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

I use AI proofreading tools to improve some texts.

I welcome constructive criticism and dialogue.

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

This article is part of the AI Coding Tip series.

Maxi Contieri

Jan 21

AI Coding Tips

#webdev #ai #programming #beginners

Comments

1 min read

AI Coding Tip 015 - Force the AI to Obey You

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

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

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

Common Mistake ❌

You write a long skill file with dozens of rules.

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

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

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

Problems Addressed 😔

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

How to Do It 🛠️

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

Benefits 🎯

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

Context 🧠

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

They process tokens sequentially, but attention is not uniform.

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

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

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

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

Small skills rarely have this problem.

Large, multi-purpose skills suffer from it constantly.

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

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

The AI commits to the constraints before it encounters exceptions.

Prompt Reference 📝

Bad Prompt 🚫

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

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

The language rule and the API rule are buried.

The AI will forget them or apply them inconsistently.

Good Prompt 👉

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

---

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

---

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

The AI reads the rules first, then the context.

The repetition at the end reinforces both constraints.

Considerations ⚠️

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

Type 📝

[X] Semi-Automatic

Limitations ⚠️

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

Tags 🏷️

Context Window

Level 🔋

[X] Intermediate

Related Tips 🔗

Maxi Contieri

Mar 31

AI Coding Tip 013 - Use Progressive Disclosure

#ai #coding #llm #productivity

Comments 1

5 min read

Maxi Contieri

Apr 7

AI Coding Tip 014 - Use Nested AGENTS.md Files

#ai #webdev #programming #productivity

Comments

4 min read

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

Conclusion 🏁

A long skill file doesn't enforce itself.

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

Put critical rules first.

Mark them explicitly.

Repeat the non-negotiables at the end.

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

From constraints to context, not the other way around.

More Information ℹ️

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

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

Also Known As 🎭

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

Disclaimer 📢

The views expressed here are my own.

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

I use AI proofreading tools to improve some texts.

I welcome constructive criticism and dialogue.

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

This article is part of the AI Coding Tip series.

Maxi Contieri

Jan 21

AI Coding Tips

#webdev #ai #programming #beginners

Comments

1 min read

Code Smell 319 - Hardcoded Stateless Properties

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

Don't turn collaborators into permanent roommates

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

Problems 😔

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

Solutions 😃

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

Refactorings ⚙️

Maxi Contieri

Mar 9 '25

Refactoring 024 - Replace Global Variables with Dependency Injection

#webdev #programming #javascript #beginners

Comments

7 min read

Maxi Contieri

Jul 11 '25

Refactoring 030 - Inline Attributes

#webdev #programming #javascript #beginners

Comments

7 min read

Maxi Contieri

Jul 4 '22

Refactoring 007 - Extract Class

#webdev #beginners #javascript #tutorial

Comments

1 min read

Context 💬

Hardcoding a stateless class in the constructor creates permanent coupling.

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

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

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

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

Sample Code 💻

Wrong 🚫

class UserProcessor {
  private provider: MockDataProvider;

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

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

Right 👉

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

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

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

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

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

Detection 🔍

Look for the new keyword inside constructors.

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

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

Tags 🏷️

Premature Optimization

Level 🔋

[X] Beginner

Why the Bijection Is Important 🗺️

Software should mimic a MAPPER of the real world.

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

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

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

This keeps your simulation flexible and accurate.

AI Generation 🤖

AI generators frequently create this smell.

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

AI Detection 🧲

AI can easily detect this smell without explicit instructions.

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

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

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

Try Them! 🛠

Remember: AI Assistants make lots of mistakes

Suggested Prompt: remove the cached attribute

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

Conclusion 🏁

Storing stateless dependencies as instance variables makes your code rigid.

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

Relations 👩‍❤️‍💋‍👨

Maxi Contieri

Oct 25 '20

Code Smell 06 - Too Clever Programmer

#codenewbie #tutorial #beginners

Comments 7

2 min read

Maxi Contieri

Nov 8 '20

Code Smell 20 - Premature Optimization

#oop #developing #coding #codesmell

Comments

2 min read

More Information 📕

Maxi Contieri

Feb 6 '21

Coupling: The one and only software design problem

#webdev #programming #oop #tutorial

Comments 2

5 min read

Disclaimer 📘

Code Smells are my opinion.

Credits 🙏

Photo by Possessed Photography on Unsplash

Coupling is the enemy of change

Rich Hickey

Maxi Contieri

Dec 28 '20

Software Engineering Great Quotes

#codenewbie #programming #quotes #software

Comments

75 min read

This article is part of the CodeSmell Series.

Maxi Contieri

May 21 '21

How to Find the Stinky parts of your Code

#codenewbie #tutorial #codequality #beginners

Comments

14 min read

AI Coding Tip 014 - Use Nested AGENTS.md Files

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

Context is precious. Don't waste it.

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

Common Mistake ❌

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

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

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

This wastes context and weakens the guidance that matters.

Problems Addressed 😔

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

How to Do It 🛠️

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

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

Benefits 🎯

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

Context 🧠

AI coding assistants load context files to understand your project.

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

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

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

The root file sets foundations.

Subdirectory files add specifics.

Local files hold personal quirks.

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

Remember, you always need to manage your context wisely.

Prompt Reference 📝

Bad Prompt:

Here are all the conventions for my project:

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

Now help me fix this React component.

Good Prompt:

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

use functional components, no class components,

Tailwind only for styling, 

test with React Testing Library.

Help me fix this component.

Considerations ⚠️

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

Type 📝

[X] Semi-Automatic

Limitations ⚠️

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

Tags 🏷️

Standards

Level 🔋

[X] Intermediate

Related Tips 🔗

Maxi Contieri

Feb 4

AI Coding Tip 005 - Keep Context Fresh

#webdev #programming #ai #tutorial

Comments

4 min read

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

Conclusion 🏁

You don't need one perfect AGENTS.md.

You need the right rules in the right place.

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

Your AI works better with less noise.

More Information ℹ️

Stop Using Claude Code as a ChatBot

Claude Code CLAUDE.md documentation

Cursor Rules documentation

GitHub Copilot custom instructions

OpenAI ChatGPT custom instructions

Aider conventions file

Cody context and instructions

Monorepo tooling with Nx

Context window management in LLMs

Prompt engineering guide

Also Known As 🎭

Hierarchical context files
Layered instructions
Nested AI rules
Scoped assistant configuration

Tools 🧰

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

Disclaimer 📢

The views expressed here are my own.

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

I use AI proofreading tools to improve some texts.

I welcome constructive criticism and dialogue.

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

This article is part of the AI Coding Tip series.

Maxi Contieri

Jan 21

AI Coding Tips

#webdev #ai #programming #beginners

Comments

1 min read

AI Coding Tip 013 - Use Progressive Disclosure

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

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

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

Common Mistake ❌

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

Your context window fills up immediately.

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

The AI gets lost in noise and disobeys your commands.

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

Problems Addressed 😔

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

How to Do It 🛠️

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

Benefits 🎯

The AI loads only the files it needs.

You save 90% of tokens on irrelevant skill content.

Response times stay fast even with complex skills.

Your context window stays clean for follow-up questions.

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

Context 🧠

Agentic skills can be massive.

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

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

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

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

The AI only reads what matters.

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

You create conditional rules in your main skill file.

You include response templates so answers stay consistent.

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

How Skills Work 🔄

Skills implement progressive disclosure at three stages:

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

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

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

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

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

Still no unnecessary files or code loaded yet.

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

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

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

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

Prompt Reference 📝

Bad Prompt:

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

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

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

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

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

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

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

Context window fills up fast.

Good Prompt:

# SKILL.md (800 tokens - Modular)

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

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

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

declaration.md (1,200 tokens):

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

array.md (1,500 tokens):

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

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

Context stays clean for follow-up questions.

Considerations ⚠️

Define your keywords upfront so the AI recognizes them consistently.

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

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

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

If your skill includes scripts, review them carefully.

Scripts can create security risks if they run without review.

Type 📝

[X] Semi-Automatic

Limitations ⚠️

Progressive disclosure works best when keywords are distinctive.

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

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

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

Keywords must be clear or the AI loads files unpredictably.

Tags 🏷️

Standards

Level 🔋

[X] Intermediate

Related Tips 🔗

Maxi Contieri

Jan 6

AI Coding Tip 001 - Commit Before Prompt

#ai #development #coding #webdev

Comments

3 min read

Maxi Contieri

Feb 4

AI Coding Tip 005 - Keep Context Fresh

#webdev #programming #ai #tutorial

Comments

4 min read

Maxi Contieri

Mar 3

AI Coding Tip 009 - Compact Your Context

#webdev #ai #programming #tutorial

Comments 1

4 min read

Conclusion 🏁

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

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

Include templates so responses stay consistent.

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

More Information ℹ️

Agent skills progressive disclosure

Claude Token Counting Guide

Context Windows and Token Limits

Prompt Engineering Patterns

UX Progressive Disclosure

Information Architecture Best Practices

Cognitive Load Theory

Efficient Prompt Design

API Cost Optimization

Code Context Patterns

Also Known As 🎭

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

Tools 🧰

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

Disclaimer 📢

The views expressed here are my own.

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

I use AI proofreading tools to improve some texts.

I welcome constructive criticism and dialogue.

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

This article is part of the AI Coding Tip series.

Maxi Contieri

Jan 21

AI Coding Tips

#webdev #ai #programming #beginners

Comments

1 min read

AI Coding Tip 012 - Understand All Your Code

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

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

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

Common Mistake ❌

You ask an AI agent to implement a feature.

It returns 200 lines of code.

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

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

But you never read the code.

Three weeks later, a security issue appears in production.

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

You didn't catch it because you never looked.

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

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

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

Problems Addressed 😔

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

Maxi Contieri

Nov 4 '25

Code Smell 313 - Workslop Code

#webdev #programming #ai #web3

Comments

7 min read

How to Do It 🛠️

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

Benefits 🎯

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

Context 🧠

AI agents are fast. That speed creates pressure.

You feel like slowing down to read breaks the momentum.

It doesn't. It saves you.

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

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

You do. That context is irreplaceable.

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

Asking questions is not a sign of weakness.

It is how you stay in control.

The AI won't judge you for asking.

It will give you a better answer.

Prompt Reference 📝

Bad Prompt:

Implement user authentication,

add it to the project,

commit and push to the main branch.

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

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

Good Prompt:

Implement a login function using JWT.

Use RS256 signing.

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

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

*This prompt sets expectations.*

*You get code AND an explanation.*

*You know what to verify.*

Considerations ⚠️

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

Type 📝

[X] Semi-Automatic

Limitations ⚠️

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

Tags 🏷️

Readability

Level 🔋

[X] Beginner

Related Tips 🔗

Maxi Contieri

Feb 13

AI Coding Tip 006 - Review Every Line Before Commit

#ai #programming #development #softwaredevelopment

Comments 1

7 min read

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

Conclusion 🏁

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

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

Speed without understanding is just faster mistakes.

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

More Information ℹ️

The Pragmatic Programmer - Your Code, Your Responsibility

OWASP Top Ten - Common Security Risks in Code

Code Review Best Practices - Google Engineering

Martin Fowler - Code Smells

GitHub Copilot Security Research - Risks of AI Code

ACM Code of Ethics - Professional Responsibility

Stack Overflow Blog - How AI Changes Code Ownership

IEEE Software Engineering Standards

CWE - Common Weakness Enumeration

Also Known As 🎭

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

Tools 🧰

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

Disclaimer 📢

The views expressed here are my own.

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

I use AI proofreading tools to improve some texts.

I welcome constructive criticism and dialogue.

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

This article is part of the AI Coding Tip series.

Maxi Contieri

Jan 21

AI Coding Tips

#webdev #ai #programming #beginners

Comments

1 min read

AI Coding Tip 011 - Initialize Agents.md

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

Summarize your architecture rules and give your AI a persistent memory

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

Common Mistake ❌

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

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

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

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

Problems Addressed 😔

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

How to Do It 🛠️

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

Benefits 🎯

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

You get consistent results without extra effort.

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

Context 🧠

AI assistants start every session with a blank slate.

They don't remember what you told them yesterday.

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

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

Prompt Reference 📝

Bad Prompt:

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

Good Prompt:

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

/Init

Considerations ⚠️

Keep the generated file short.

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

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

Type 📝

[X] Semi-Automatic

Limitations ⚠️

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

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

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

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

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

Tags 🏷️

Standards

Level 🔋

[X] Beginner

Related Tips 🔗

AI Coding Tip 006 - Review Every Line Before Commit

Maxi Contieri ・ Feb 13

#ai #programming #development #softwaredevelopment

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

Conclusion 🏁

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

More Information ℹ️

OpenCode /Init

Claude Code: CLAUDE.md

.cursorrules in Cursor

Windsurf rules

Also Known As 🎭

Project-AI-Onboarding
Context-Bootstrapping

Tools 🧰

Claude Code
OpenCode
Cursor (via .cursorrules)

Disclaimer 📢

The views expressed here are my own.

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

I use AI proofreading tools to improve some texts.

I welcome constructive criticism and dialogue.

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

This article is part of the AI Coding Tip series.

AI Coding Tips

Maxi Contieri ・ Jan 21

#webdev #ai #programming #beginners

AI Coding Tip 010 - Access All Your Code

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

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

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

Common Mistake ❌

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

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

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

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

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

Problems Addressed 😔

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

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

How to Do It 🛠️

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

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

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

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

Review the proposed plan in the terminal.

Approve the changes to update your local files.

Let the agent run your tests and fix failures automatically.

Benefits 🎯

Full project context through local AST and RAG indexing.

Self-healing code through automated shell feedback loops.

Multi-file edits in a single prompt.

Parallel development using multiple agent instances.

Iterative incremental learning and experimentation. Baby steps.

Context 🧠

We were all blown away when ChatGPT came out.

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

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

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

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

Prompt Reference 📝

Bad Prompt

// Please fix the login bug in this snippet:

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

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

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

Good Prompt

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

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

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

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

Considerations ⚠️

CLI agents have a learning curve.

Always review all changes before committing them.

Use a sandbox environment if you run untrusted code.

Type 📝

[X] Semi-Automatic

Limitations ⚠️

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

Web chats work better for creative brainstorming or generating images.

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

Tags 🏷️

Complexity

Level 🔋

[X] Intermediate

Related Tips 🔗

Maxi Contieri

Jan 20

AI Coding Tip 003 - Force Read-Only Planning

#ai #programming #chatgpt #code

Comments

3 min read

Maxi Contieri

Feb 13

AI Coding Tip 006 - Review Every Line Before Commit

#ai #programming #development #softwaredevelopment

Comments 1

7 min read

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

Run local models if you need 100% privacy.

Conclusion 🏁

Move your AI assistant to the terminal.

You'll work faster and make fewer mistakes.

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

More Information ℹ️

Why CLIs Are Better for AI Coding Agents Than IDEs

How Cursor Actually Indexes Your Codebase

Aider - AI Pair Programming in your Terminal

Claude Code Overview

OpenCode vs Claude Code: Comparing AI Coding Agents

AI Coding Assistants for Large Codebases

Boosting My Developer Productivity with AI in 2025

OpenCode Documentation

Introducing Advanced Tool Use on the Claude Developer Platform

What is OpenCode? - AI Quick Reference

Also Known As 🎭

Agentic Coding

Terminal Agents

Autonomous Coding Loops

Tools 🧰

Claude Code, OpenCode, Aider, Codex CLI.

Disclaimer 📢

The views expressed here are my own.

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

I use AI proofreading tools to improve some texts.

I welcome constructive criticism and dialogue.

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

This article is part of the AI Coding Tip series.

Maxi Contieri

Jan 21

AI Coding Tips

#webdev #ai #programming #beginners

Comments

1 min read

AI Coding Tip 009 - Compact Your Context

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

Stop the memory rot

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

Common Mistake ❌

You keep a single, long conversation open for hours.

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

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

Stop the memory rot

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

Common Mistake ❌

You keep a single, long conversation open for hours.

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

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

Problems Addressed 😔

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

How to Do It 🛠️

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

Benefits 🎯

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

Context 🧠

Large Language Models have limited attention.

Long context windows are a trap.

Many modern models offer a very large context window.

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

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

Prompt Reference 📝

Bad Prompt

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

Also, remember that we changed the database schema 

Three hours ago in this chat.

Add the unit tests as I described above.

Now, refactor the whole component.

Good Prompt

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

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

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

Refactor the LoginComponent` to use these.

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 🔗

Maxi Contieri

Jan 27

AI Coding Tip 004 - Use Modular Skills

#ai #webdev #programming #beginners

Comments

4 min read

Maxi Contieri

Feb 4

AI Coding Tip 005 - Keep Context Fresh

#webdev #programming #ai #tutorial

Comments

4 min read

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

Lost in the Middle: How Language Models Use Long Context

LLMLingua: Prompt Compression for LLMs

How to Manage Context in AI Coding

Avoiding LLM Hallucinations

Prompt Engineering Guide: Context Management

Understanding Token Limits

Claude Context Window Best Practices

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.

Maxi Contieri

Jan 21

AI Coding Tips

#webdev #ai #programming #beginners

Comments

1 min read

functions.

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

Maxi Contieri — Tue, 24 Feb 2026 11:00:00 +0000

Learn guided by the domain

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

Spec Driven Development

Kent Beck Critizing Spec-Driven Development

Kent Beck Earn and Learn

Addy Osmani Coding Workflow

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.

Maxi Contieri

Jan 21

AI Coding Tips

#webdev #ai #programming #beginners

Comments

1 min read

AI Coding Tip 007 - Avoid Malicious Skills

Maxi Contieri — Tue, 17 Feb 2026 04:14:54 +0000

Avoid the Agentic Trojan Horse

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.

Even careful developers can miss these details when rushing.

Problems Addressed 😔

Information stealers search for 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.

Your adversaries invoke Arbitrary Code Execution using unvalidated WebSocket connections.

How to Do It 🛠️

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

This measure prevents the agent from accessing your primary filesystem.

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

Making a code review You can find hidden curl commands, base64-encoded strings and obfuscated code that try to get to malicious IPs like 91.92.242.30.

You can help yourself with security scanners like Clawdex or Koi Security's tool.

The tools check the 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 also reduce the risk of identity theft through session hijacking.

You avoid Package Hallucination

Context 🧠

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

Attackers now flood registries with "skills" that appear to be 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 endpoint protection. It adds a layer for AI-specific supply chain risks.

Tags 🏷️

Security

Level 🔋

[X] Intermediate

Related Tips 🔗

Maxi Contieri

Jan 27

AI Coding Tip 004 - Use Modular Skills

#ai #webdev #programming #beginners

Comments

4 min read

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

Malicious moltbot skills

Maxi Contieri

Jul 13 '24

Code Smell 258 - Secrets in Code

#webdev #beginners #programming #security

Comments

2 min read

Maxi Contieri

Dec 21 '24

Code Smell 284 - Encrypted Functions

#webdev #programming #security #hacking

Comments

5 min read

Maxi Contieri

Aug 13 '24

Code Smell 263 - Squatting

#webdev #beginners #programming #python

Comments

3 min read

Maxi Contieri

Jan 20

AI Coding Tip 003 - Force Read-Only Planning

#ai #programming #chatgpt #code

Comments

3 min read

Maxi Contieri

May 12 '25

Code Smell 300 - Package Hallucination

#security #webdev #json #codesmell

Comments

6 min read

Dark news

Beyond the Hype

Bit Defender

Hacker News: Researchers Find 341 Malicious ClawHub Skills Stealing Data from OpenClaw Users

Also Known As 🎭

Agentic Supply Chain Poisoning

ClickFix AI Attacks

Tools 🧰

OpenClaw

Clawdex

Koi Security's tool

Disclaimer 📢

The views expressed here are my own.

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

I use AI proofreading tools to improve some texts.

I welcome constructive criticism and dialogue.

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

This article is part of the AI Coding Tip series.

Maxi Contieri

Jan 21

AI Coding Tips

#webdev #ai #programming #beginners

Comments

1 min read

AI Coding Tip 006 - Review Every Line Before Commit

Maxi Contieri — Fri, 13 Feb 2026 11:00:00 +0000

You own the code, not the AI

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~ you will have to clean up later.

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

You skip a 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. And you want to keep your job and be seen as mandatory for the software engineering process.

Problems Addressed 😔

Security vulnerabilities and flaws: AI generates code with Not sanitized inputs SQL injection, XSS, Email, 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 🛠️

Ask the AI to generate the code you need using English language
Read every single line the AI produced, understand it, and challenge it if necessary
Check that the solution matches your actual requirements
Verify the code handles edge cases and errors
Look for security issues (injection, auth, data exposure)
Test the code locally with real scenarios
Run your linters, prettifiers and security scanners
Remove any debug code or comments you don't need
Refactor the code to match your team's style
Add or update tests for the new functionality (ask the AI for help)
Write a clear commit message explaining what changed
Only then commit the code
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)