DEV Community: alifurkan gökçe

My open-source project's first contribution came from an AI agent. It disclosed itself.

alifurkan gökçe — Tue, 08 Sep 2026 06:20:53 +0000

Last week I published a small open-source tool — a linter for the instruction files coding agents read (CLAUDE.md, AGENTS.md, skills). Then two things happened in two days, and together they changed how I think about reviewing contributions.

The first pull request wasn't from a human

A PR appeared. Clean diff, two tests, and a scoping decision argued in a comment rather than silently made. The description ended with this:

This pull request was implemented and validated autonomously by OpenAI Codex using the LunaMeerkats account. No human review or authorship is being claimed.

The change itself was a real bug in my code: my file walker skipped any directory whose name started with .git, which also swallowed .github. Since .git was already in the ignore list, that prefix test only ever excluded .github — leaving the Copilot instruction-file support unreachable since the day it shipped. Documented in my README, typed, wired up, and dead.

What made it easy to merge wasn't the code, it was the reasoning. The PR claimed its change introduced no new findings, and argued why: every other consumer of that walker is path- or basename-scoped, so widening the walk couldn't reach them. I verified it the hard way anyway — diffed the finding sets before and after on three real repositories, identical on all three — but I was checking a stated argument, not guessing at intent.

Then a human read the source and filed eleven issues

A day later someone went through the code and opened eleven issues. Not drive-by complaints: each one had a file:line diagnosis, a repro, and often the fix. Two were serious. An unreadable Makefile took the whole scan down with an unhandled exception — while the package.json branch four lines above it was already wrapped in a try. And --fix wrote replacements through String.replace with a string pattern, so a $& or $` in a path spliced surrounding text into the user's file instead of the text I'd shown them. A linter that silently corrupts the file it's checking is about the worst thing I could have shipped.

All eleven are fixed. Two releases in a day, each regression test verified to fail on the unpatched source first.

What I took from it

Disclosed agent contributions can clear the bar, and the bar shouldn't move. I reviewed that PR line by line, tested the claim it made about itself, and merged it on its merits. If it had been sloppy I'd have closed it, exactly as I would for a human. What made it reviewable was the disclosure plus an argument I could check.

The most valuable thing a project receives isn't a star — it's someone who reads the source. Mine had nine stars when a stranger sat down with it and found eleven real defects. No metric I track would have told me that much.

And the irony is doing work. A tool that exists to stop agents from trusting stale information had its own bugs found by an agent and a careful human, in that order.

The project is MIT and runs entirely locally: driftlint.

Curious how others are handling this: if a PR discloses that an agent wrote it, does that change your review, and should it?

Three ways your coding agent silently never reads your instructions

alifurkan gökçe — Mon, 07 Sep 2026 06:53:57 +0000

You write instructions for your coding agent. It ignores one of them. You rewrite it more forcefully, in bold, with "IMPORTANT" in front. It still ignores it.

Before blaming the model, check whether it ever saw the text. Each of the three cases below is documented behaviour of a tool you already use, each one drops part of your instructions on the floor, and none of them prints a warning.

1. Cursor ignores `.md` files in `.cursor/rules`

Project rules in Cursor must use the .mdc extension. Cursor's own docs put it plainly: a plain .md file there is ignored by the rules system, because it has nowhere to declare the description, globs and alwaysApply frontmatter that tells Cursor when to apply it.

So a file sitting in exactly the right directory, with exactly the right content, does nothing. No error at startup, no "rule skipped" line, nothing in the UI.

Ten-second check:

find .cursor/rules -name '*.md' 2>/dev/null

Any output is a rule that isn't loading. Rename to .mdc and add the frontmatter.

A detail that makes this worse: people who set up .md rules a while ago report that they used to work. If that's right, a working setup stopped working at some point during an update, and nothing announced it — so "I checked this once" is not protection.

2. Codex truncates your AGENTS.md files — as a set, not one by one

Codex reads the AGENTS.md files that apply to your working directory: a global one, the repo root, and the nested ones on the path. It concatenates them, and the 32 KB truncation applies to that combined payload.

This is the part that catches people, because every individual file looks fine:

AGENTS.md              12 KB   ✓ fine
packages/api/AGENTS.md 12 KB   ✓ fine
packages/web/AGENTS.md 12 KB   ✓ fine
                       -----
                       36 KB   ✗ 4 KB never reaches the model

Nobody wrote a "too big" file. The rule you carefully put at the bottom of the last one simply isn't there when the model reads.

Check it:

find . -name AGENTS.md -not -path '*/node_modules/*' | xargs wc -c

Add your global ~/.codex/AGENTS.md to the total, and remember only the files on the path to your working directory get concatenated — a file under packages/web doesn't count against you while you're working in packages/api.

I hit a real one while testing this: a checkout with four AGENTS.md files totalling 65.6 KB, 33.6 KB of it truncated away, no single file anywhere near the limit.

3. Claude Code truncates skill descriptions at 1,536 characters

Skills load their body on demand, which is the point — but the model only knows a skill exists from its listing, and the docs are specific: the combined description and when_to_use text is truncated at 1,536 characters in that listing.

Write a thorough description with five trigger examples and the last two are gone. The skill still exists, still works when invoked by name, and quietly stops being chosen on its own — which reads exactly like "the model is being lazy".

Put the key use case in the first sentence. Detail belongs in the body, which costs nothing until the skill runs.

The pattern

All three share a shape worth internalising: the failure is invisible from the inside. Your file is on disk. Your editor shows it. Code review shows it. The agent read a subset of it and had no way to tell you which part.

Regular documentation rots the same way, but a human reader notices when a doc is stale — the paths look wrong, the commands don't exist any more. An agent doesn't notice. It follows the text with complete confidence, including the part that stopped being true in March.

That second half is measurable. I scanned 118 popular open-source repositories with agent context files: 59% contained at least one hard dead reference — a file path or a script the instructions still name and the repo no longer has. Careful teams, well-maintained projects; the rot is just silent.

What to actually do

The manual checks above take a minute and catch a lot. Beyond that:

Keep one source of truth for CLAUDE.md and AGENTS.md. Claude Code reads the first, most other tools read the second, and asking for both is the most-upvoted request on the Claude Code tracker — 5,200+ reactions, marked not planned. An @AGENTS.md import inside CLAUDE.md works; a symlink works when the content is genuinely identical; two hand-maintained copies drift within a week.
Treat instruction files as code: they make claims about paths, scripts and links that CI can verify.
Re-check after tool updates, not just after your own edits. Case 1 is the reason.

For the automated version I wrote driftlint (disclosure: mine, MIT, zero runtime dependencies, no account, nothing leaves your machine):

npx @alifurkangokce/driftlint

It checks all three limits above plus the drift half: dead file paths with did-you-mean fixes, removed npm scripts and make targets, markdown links whose target or heading moved, hooks and MCP servers pointing at scripts that don't exist, and CLAUDE.md ↔ AGENTS.md copies that have diverged.

But the tool is secondary. The idea worth keeping is the first one: when an agent ignores an instruction, check whether it was ever handed the instruction. Half the time, it wasn't.