AGENTS.md: The One File That Keeps AI Coding Agents From Breaking Your Repo

·1 views

AI coding agents like Claude Code, Codex, Cursor, and GitHub Copilot have become standard tools in real software teams by 2025, but without proper guidance they often guess commands incorrectly, delete code, or commit unwanted files. AGENTS.md is a markdown file committed to a repository's root that instructs AI agents on commands, conventions, architecture, and project-specific rules before they touch any code. A developer sharing production experience recommends keeping the file under 300 lines, covering setup commands, workflow expectations, architecture pointers, style rules, and a list of prohibited actions. Common mistakes include treating the file like full documentation, duplicating README content, or including secrets, since the file is committed and potentially public. A free, MIT-licensed starter template called agentsmd-kit has been made available to help teams adopt a consistent structure quickly.

Read the full story at DEV Community

This is an AI-generated summary. ShortSingh links to the original source for the complete article.

Discussion (0)

How Replacing Global State with Explicit Dependencies Rescues Legacy Codebases

A software developer recounts inheriting a sprawling legacy codebase built with mixed PHP, JavaScript, and Bash, where pervasive global singletons made even minor changes unpredictable and dangerous. Critical objects like a Config singleton and a static Logger were accessed directly throughout the code, causing hidden side effects that were nearly impossible to trace or test in isolation. The turning point came after reading Michael Feathers' 'Working Effectively with Legacy Code', which introduced the concept of seams — points where behavior can be changed or tested without altering existing code. The developer adopted the practice of passing dependencies explicitly as parameters rather than relying on globals, which improved code transparency, testability, and safety. This architectural shift allowed unit tests to use mock objects without bootstrapping the full application, dramatically reducing debugging time and making the codebase easier to maintain.

0 comments Read more at DEV Community

ProgrammingDEV Community ·

Postgres lock bug from unclean shutdown took down entire Next.js site

A developer's Next.js site began returning HTTP 500 errors on every request after a Postgres lock conflict caused the background worker to fail on boot. The root cause was a leftover lock on the pgboss.queue table from a previous unclean database shutdown, triggering error code 55P03 (lock_not_available) each time the worker tried to initialize. Because the worker was booted inside the web process via Next.js's instrumentation hook, its failure brought down the entire site rather than degrading gracefully. The fix involved catching worker boot errors so the web server stays up regardless, and adding a retry loop with exponential backoff so the worker self-heals once the lock clears. A secondary bug was also identified where the 'started' flag was set before a successful boot, permanently blocking any retries after a failure.

0 comments Read more at DEV Community

ProgrammingDEV Community ·

HMRC Fraud Prevention Headers: What .NET Developers Often Get Wrong

HMRC's Making Tax Digital APIs require a set of mandatory Fraud Prevention Headers with every API call, and incorrect or incomplete headers can silently lower a submission's trust score or trigger an outright rejection. A key pitfall for backend developers is that several required headers — such as Gov-Client-Device-ID, Gov-Client-Screens, and Gov-Client-Timezone — must reflect the end user's actual device and browser, not server-generated values. In a typical SPA-and-API architecture, this means client-side code must capture and forward these values to the backend, which then relays them to HMRC. Server-side headers like Gov-Vendor-Version and Gov-Vendor-Product-Name, which describe the vendor's software, are the only ones a backend service can legitimately generate on its own. A recommended .NET implementation uses a DelegatingHandler to assemble the full header set before each outbound HttpClient call, maintaining a clear split between client-collected and server-generated data.

0 comments Read more at DEV Community

ProgrammingDEV Community ·

How AI and Sensor Fusion Are Transforming Military Decision-Making

Artificial intelligence is reshaping modern warfare by enabling faster detection, decision-making, and targeting through machine learning models and sensor fusion systems. Military data pipelines now integrate satellite imagery, drone footage, acoustic sensors, and radio-frequency data to build a real-time operational picture that human analysts alone cannot process at speed. Autonomous and semi-autonomous weapons systems range from rule-based missile defences to AI-assisted targeting tools capable of operating with minimal human intervention. A key concern is whether formal human oversight remains meaningful when operators must rapidly approve dozens of AI-generated recommendations under time pressure. Experts stress that explainability, audit trails, and clear accountability are essential, as errors in these systems can cause civilian casualties, escalate conflicts, or trigger strategic miscalculations.

0 comments Read more at DEV Community