Halloween DealsAmazon USHalloween week deals: useful picks before month-endAmazon US: current deals, useful picks and tech finds.Check DealsSlow PC?RecommendedPC slow today? Run a repair scan before it gets worseResolve common Windows issues and optimize system performance.Scan NowHalloween DealsAmazon USOctober picks are moving - compare before checkoutAmazon US: current deals, useful picks and tech finds.See Picks×
FREEDOM251

Freedom251 › Blog › AGENTS.md

How to Fix a Coding Agent Setup That Produces Garbage

By Freedom251 Team · · 11 min read

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

If an AI coding agent keeps returning unusable code, change the workflow before you change the model. Ashley Childress’s practical article, AI Isn’t Stupid. Your Setup Is. 🛠️, argues that unclear tasks, scattered instructions, unnecessary tools and weak validation can make a capable agent look incompetent. Her concise verdict is: “The agent isn’t the problem—the setup is.”

That is a workflow diagnosis, not a controlled finding that setup always matters more than model capability. Childress published the article on May 2, 2026, and edited it on May 7, 2026. The recommendations below are presented as her experience and judgment, with limits called out where the article does not provide benchmarks or universal rules.

As an Amazon Associate I earn from qualifying purchases.

What Childress’s argument actually means

The complaint she is addressing is familiar: “I tried an agent flavor of the week and it gave me garbage.” Childress’s response is that an agent cannot reliably infer an undefined outcome, hidden constraints or an appropriate level of autonomy. A request that sounds simple to a person may leave the model guessing about architecture, acceptance criteria, error handling, permitted changes and what must not be touched.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Her ten-part workflow covers model selection, planning, instruction files, skills, MCP integrations, testing, shortcut policies and conversation resets. The article does not report a comparative benchmark, a named statistic or a controlled experiment. Haiku, Sonnet and Opus are examples she uses in May 2026; the piece does not establish a universal ranking, price advantage or current availability for those models.

#1 Best Overall
Elebase USB to USB C Adapter for iPhone 18 Pro Max,USBC Car Charger Adapter | 4Pack Type C Female to A Male Cable Converter for Apple Duo 17 16 15 14 Plus,iWatch Watch 12 11 10,iPad 9 8 Air,Airpods 5 4
  • Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
  • Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
  • Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
  • Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
  • 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.

Use the advice as a set of adjustable engineering practices. The higher the risk of a mistake, the more explicit the specification and the more independent the validation should be.

Start with a setup diagnosis, not a model swap

Before moving a task to another agent, inspect the conditions under which the failure occurred. The same model can produce very different results when the prompt, repository instructions, available tools and test loop change.

  • Undefined outcome: You asked for a feature but did not describe what success looks like.
  • Hidden scope: The agent changed unrelated files because boundaries were not stated.
  • Conflicting instructions: Several files or prompts contain different rules for the same project.
  • Missing context: The agent lacks the stack decision, domain constraint, schema, API contract or relevant tool.
  • Unverified output: You accepted a plausible diff without running tests or checking behavior manually.
  • Looping correction: Repeated messages produce small variations of the same wrong approach.

This checklist does not prove that the model is correctable in every case. It identifies setup variables you can change before drawing a conclusion about capability.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

1. Match the model to task complexity and specification quality

Childress recommends choosing a model for both the work and the quality of the specification. A small, clearly bounded change can be a better fit for a less costly model. A tangled task with interacting requirements may justify a more capable model, especially when the specification cannot be made simple without losing important detail.

Task condition Setup implication Childress’s example framing
Simple and clearly specified Use a less costly model when the acceptance criteria, files and constraints are explicit. Haiku is named as an example; no benchmark or current price is supplied.
Moderate complexity with several decisions Provide a written plan and enough repository context before implementation. Sonnet is named as an example; the article does not claim it is universally best.
Tangled, ambiguous or high-consequence work Spend more effort on planning and consider a more capable model when the task still requires substantial reasoning. Opus is named as an example; no comparative test establishes a ranking.

Do not turn these labels into a procurement rule. The article does not compare latency, token pricing, context limits, coding accuracy or availability. A model change is sensible when the task genuinely exceeds the current model’s reasoning or context capacity, not merely because an underspecified request failed.

2. Plan in chat before changing the codebase

Childress’s second recommendation is to use the conversation as a design and clarification phase. Keep the agent from editing until both sides have a shared definition of the work.

Rank #2
Sale
Anker USB-C Hub, 5-in-1 USB Hub for Laptops, 4K HDMI Multiport Adapter | USB C Dongle with 90W Max Power Delivery, 3×5Gbps USB A Data Ports, for MacBook, Dell, and More (Charger Not Included)
  • 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
  • 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
  • Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
  • 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
  • What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
  1. State the desired outcome. Describe the user-visible behavior or engineering result, not just the name of a feature.
  2. Declare meaningful stack choices. Identify the language, framework, database, deployment target and existing patterns that constrain implementation.
  3. Define acceptance criteria. List observable conditions that must be true for the work to be complete.
  4. Specify positive cases. Give representative valid inputs and expected outputs.
  5. Specify negative and error cases. Explain what should happen for invalid input, unavailable dependencies, permission failures and malformed state.
  6. Call out edge cases. Include empty data, limits, concurrency, retries, time zones, localization or other boundaries that matter to this feature.
  7. Write explicit non-goals. Say which refactors, migrations, compatibility changes or unrelated cleanups are out of scope.
  8. Ask for a proposed plan. Have the agent identify files, dependencies, risks and tests before it writes code.
  9. Resolve open questions. Correct assumptions in the plan, then authorize implementation only after the unresolved choices are visible.

A useful plan is specific enough that another engineer could review it without guessing what the agent was meant to do. If the agent cannot explain how its plan satisfies each acceptance criterion, the implementation phase is premature.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

3. Keep project instructions coherent

Childress prefers one AGENTS.md file as the project’s source of truth, with short links from tool-specific files when an agent expects a different entry point. The purpose is to avoid maintaining several copied versions of the same rules.

That is her workflow choice, not a convention guaranteed by every coding agent. Check the documentation and loading behavior of the specific system you use: some tools look for different filenames, directory scopes or precedence rules. Whatever convention applies, make the authoritative rules easy to find and keep references synchronized.

A practical instruction-file structure

  • Repository-wide rules: Supported runtimes, package-manager commands, formatting, testing and security requirements.
  • Directory-specific rules: Only the constraints that differ for a service, package, frontend or infrastructure folder.
  • Tool entry point: A short pointer to the authoritative file rather than a second copy of all rules.
  • Change policy: What the agent may edit, what requires confirmation and which generated files are off limits.

When a rule changes, update the source of truth first and verify that every tool-specific pointer still reaches it. Conflicting instructions are not additional context; they are ambiguity.

4. Write instructions for repeated agent use

An instruction file loaded into context repeatedly should be concise, explicit and non-duplicative. Childress advises removing human-oriented introductions when they do not help the agent perform the work. Preserve the intended meaning when editing: shortening a rule must not silently weaken a security, testing or compatibility requirement.

What’s actually slowing this PC down?

Pick the symptom - the matching free tool is one click away.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Make each rule operational

  • Prefer “Run npm test before proposing a change” over “Be careful with testing.”
  • Name the command, directory or file pattern when a rule depends on one.
  • State precedence when two requirements can conflict.
  • Separate mandatory rules from suggestions so the agent can distinguish them.
  • Remove repeated wording that consumes context without adding a new decision.

Do not compress instructions until they become vague. A short rule that omits its exception or scope can create more errors than a longer, precise rule.

Rank #3
Sale
Anker USB C Hub, 7in1 Multi-Port USB Adapter, 4K@60Hz USBC to HDMI Splitter | 85W Max PD, 2 USB 3.0 & 1 USBC Data Ports, SD/TF Card Reader, for Laptops/Mac and Other Type C Devices (Charger Not Included)
  • Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
  • Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
  • Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
  • Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
  • What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.

5. Invoke essential skills explicitly

Childress does not recommend relying on automatic skill detection when a particular skill is essential to the task. Her concern is practical: detection may be uncertain, and a missed capability can change the implementation path.

If the work depends on a specific skill, name it in the request and explain what it must accomplish. For example, ask the agent to use the project’s database-migration skill for schema changes, then require it to show the migration plan and rollback implications before editing. Explicit invocation makes the dependency visible and gives you something concrete to verify.

This is not a claim that every agent handles skills identically. Follow the syntax and loading rules of the system in use, and do not invoke a skill that is irrelevant merely to make the prompt look comprehensive.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

6. Scope MCP integrations to projects that need them

Model Context Protocol (MCP) integrations can expose external tools and data sources to an agent. Childress argues against enabling every integration globally when a project does not use it. Unused integrations add clutter to the available tool surface and can make it harder to understand which capabilities are relevant.

Her article does not measure a universal token cost or establish a numerical penalty for a particular number of integrations. Treat the benefit as a context-management and governance decision rather than a quantified performance claim.

Use a project-by-project MCP policy

  • Enable only the integrations required for the repository’s tasks.
  • Keep credentials and permissions limited to the minimum necessary scope.
  • Document what each enabled integration is for and which operations it permits.
  • Disable or remove an integration when the project no longer needs it.
  • Review the tool list before asking the agent to make a high-impact change.

A narrowly scoped tool set also makes audit questions easier: you can identify which external systems the agent could access during a change.

Rank #4
Sale
UGREEN USB to USB C Adapter Combo 4-Pack, 10Gbps USB C Converter Space Gray | Data transfer & Fast charging for MacBook, iPhone 17/16/15, iPad, Samsung Galaxy, Apple Watch
  • Dual Converters, Infinite Potential:Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
  • Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
  • Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
  • Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
  • Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft

7. Test generated work repeatedly and independently

The article’s punchy “Don’t review” framing should not be read as permission to abandon human responsibility. Childress’s actual recommendation is to test the generated work repeatedly and validate it outside the agent’s own loop. Automated checks are necessary, but they are not a substitute for independent judgment.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Use multiple layers of automated testing

Check What it can reveal Typical question
Unit tests Incorrect behavior in an isolated function or component. Does each rule produce the expected result for representative inputs?
Integration tests Failures at boundaries between modules, services, databases or queues. Do the parts work together with real contracts and error handling?
End-to-end tests User-flow failures across the deployed application path. Can a user complete the acceptance scenario from start to finish?
Performance tests Latency, throughput or resource regressions under expected load. Does the change remain within the project’s response and capacity limits?
Accessibility checks Keyboard, screen-reader, contrast and interaction problems. Can people using the supported access methods complete the flow?
Static analysis Type, lint, complexity and suspicious-pattern issues. Does the code satisfy the repository’s machine-checkable standards?
Security analysis Injection, authorization, secret-handling and dependency risks. Can an untrusted input or user reach a protected operation?

Test beyond the happy path

For every acceptance criterion, exercise positive, negative, error and edge paths. A generated form that works with valid data but mishandles an empty value is not complete. A retry path that passes a unit test may still duplicate a side effect when the downstream service times out.

Validate outside the agent’s loop

Run the project’s checks yourself or in an independent CI environment rather than accepting the agent’s statement that tests passed. Read the diff, inspect the changed files and perform manual verification of the user-visible behavior. Manual validation is especially important for accessibility, visual behavior, authorization boundaries and operational assumptions that a test suite may not cover.

Keep evidence tied to the change: record which commands ran, which scenarios were checked and which limitations remain. Testing strengthens confidence; it does not transfer responsibility for the result from the engineer to the model.

Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

8. Forbid shortcuts selectively

Childress describes banning quick fixes and temporary solutions in personal projects. A shortcut that appears harmless can become permanent, obscure the real failure or create maintenance work that exceeds the original task.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

She makes an explicit exception for backward compatibility: a blanket ban is harsh for live production code and should likely be removed there. Production systems may need compatibility layers, staged migrations, versioned APIs or temporary fallbacks to protect existing users while a change rolls out.

Best Value
Sale
Anker USB C Hub, 5-in-1 USBC to HDMI Splitter with 4K Display | 85W Max PD, 1 Powered USB-C 5Gbps & 2 Powered USB-A 3.0 5Gbps Data Ports, for MacBook Pro, MacBook Air, Dell and More (Black)
  • 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
  • Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
  • Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
  • HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
  • What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
Project context Shortcut policy Reasoning
Personal or low-risk project Ban quick fixes and temporary solutions unless you consciously accept the debt. You control the scope and can prefer a clean implementation over preserving an old path.
Live production system Evaluate the shortcut against uptime, user impact, migration safety and rollback needs. Backward compatibility and staged changes may be responsible engineering, not laziness.

Write the exception into the task. Tell the agent whether compatibility is required, how long a transitional path may remain and what follow-up removes it. “Never use a workaround” is less useful than a rule matched to the project’s risk.

9. Reset a conversation that is stuck

When repeated corrections fail, Childress recommends starting a new chat with a clearer account of what has been learned. A long conversation can accumulate mistaken assumptions, contradictory edits or an increasingly narrow interpretation of the problem.

  1. Stop the current loop instead of adding another correction to it.
  2. Summarize the actual goal, constraints, failed approaches and observed symptoms.
  3. Include the relevant files, test output and acceptance criteria.
  4. State what must not change and which previous assumptions were wrong.
  5. Ask for a fresh plan before authorizing more edits.

A reset is a troubleshooting tactic, not a guarantee. If the repository requirement is impossible, the test is wrong or the model lacks the needed capability, a new context will only expose the same problem more cleanly.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

10. Treat the setup as an adjustable system

Childress’s closing lesson is to tune the whole arrangement rather than treating the model as a fixed appliance. The relevant variables include task definition, model choice, instruction quality, explicit skills, available integrations, testing depth and conversation state.

A useful operating loop is:

  1. Classify the work. Note complexity, risk, required tools and the cost of a mistake.
  2. Specify before editing. Write the outcome, stack decisions, acceptance criteria, cases and non-goals.
  3. Prepare the context. Load the authoritative project instructions, invoke essential skills and scope MCP integrations.
  4. Choose proportionately. Select a model whose capability and context fit the task; treat named model examples as time-sensitive guidance, not rankings.
  5. Implement in a reviewable increment. Require a plan and a focused diff rather than an uncontrolled rewrite.
  6. Test independently. Run automated layers, manual checks and the positive, negative, error and edge scenarios.
  7. Adjust or reset. If the result is wrong, change the failing setup variable or start a new, better-specified conversation.

This loop gives you a way to learn from a bad result without assuming that either the agent or the workflow is always solely responsible.

What the article does not establish

Childress’s article is an opinionated workflow guide based on her experience. It does not experimentally prove that setup matters more than model capability, identify a universally best agent, quantify MCP context overhead or provide a measured success rate for its recommendations. The model names and relative suitability judgments are examples from May 2026 and may change as products evolve.

It also does not eliminate the need for responsible human review. Its recommendation is stronger: give the agent a precise job, constrain its working context, test what it produces and independently verify the outcome before treating the change as finished.

Free tools Windows power users keep installed

One-click scans. No signup required.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.

AGENTS.mdAI coding agentsdeveloper workflowMCPPrompt engineeringSoftware Developmenttesting

Leave a Reply

Your email address will not be published. Required fields are marked *

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Recommended PC Tool
Recommended PC Tool
Outdated Drivers Are Slowing You DownFree scan - exact matches
PC Slower Than It Used to Be?Free scan - under a minute

Two free Windows tools

One Free Minute Could Fix That PC

Before you go - each of these free tools takes about a minute and tackles what quietly slows a Windows PC down.

Special offer. View Outbyte info, uninstall instructions, EULA, and Privacy Policy.