<!-- mobian-agent-page publisher="dailydev" canonical="https://daily.dev/posts/GIqM4P76d" -->

---
title: Don't Write Markdown Files for Your Coding Agent. Write...
description: Markdown instruction files for coding agents are recommendations, not constraints. The fix is to translate preferences into deterministic scripts: lint.sh,...
canonical: https://daily.dev/posts/don-t-write-markdown-files-for-your-coding-agent-write-scripts--giqm4p76d
twitter:card: summary_large_image
twitter:site: @dailydotdev
og:type: website
og:site_name: daily.dev
og:title: Don't Write Markdown Files for Your Coding Agent. Write Scripts. | daily.dev
og:description: Markdown instruction files for coding agents are recommendations, not constraints. The fix is to translate preferences into deterministic scripts: lint.sh,...
og:url: https://daily.dev/posts/don-t-write-markdown-files-for-your-coding-agent-write-scripts--giqm4p76d
og:image: https://api.daily.dev/og/posts/GIqM4P76d.png
og:image:alt: Don't Write Markdown Files for Your Coding Agent. Write Scripts.
og:image:width: 1200
og:image:height: 630
og:locale: en
---

> ## Documentation Index
> Fetch the complete documentation index at: https://daily.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Don't Write Markdown Files for Your Coding Agent. Write Scripts.

**[DEV](https://daily.dev/sources/devto)** · 5 min read · 22 upvotes · 4 comments

## Summary

Markdown instruction files for coding agents are recommendations, not constraints. The fix is to translate preferences into deterministic scripts: lint.sh, format.sh, test.sh, or Makefile targets that return pass or fail instead of prose to interpret. In one test, a sentence-length rule turned into a script (MAX_SENTENCE = 20) caught 9 failures across 10 of the agent's own replies. The author also describes using a CI run on a Ruby fix as a check the agent could not argue with, since the failure did not depend on the assistant's opinion of its own work. The recommendation: back every local hook with a required CI job and merge gate the agent cannot change.

## Full article

daily.dev links to this article rather than hosting it. Read it at the original source: <https://dev.to/dannwaneri/dont-write-markdown-files-for-your-coding-agent-write-scripts-j00>

## Questions this post answers

### why does my coding agent ignore the rules in my AGENTS.md or CLAUDE.md file

Markdown instructions are treated as recommendations, not constraints, because the agent has to parse, balance, and exercise judgment over them rather than follow a strict rule. Vague directives like 'use the existing logging conventions' or 'use small functions' leave room for the agent to rationalize deviations, such as assuming conflicting code means the docs are outdated.

_Developers tightening agent instructions can compare approaches to deterministic tooling on daily.dev._

### how do you make an AI coding agent follow a style rule reliably

Convert the rule into a script with a pass or fail exit condition instead of a prose instruction. One example turned the ASD-STE100 plain-English rule 'keep sentences to 20 words or fewer' into a script constant MAX_SENTENCE = 20, run through a Claude Code Stop hook after each reply, looping the agent back for another try on failure.

_Anyone scripting guardrails for agent output can track these patterns on daily.dev._

### should I trust CI test failures over my AI coding assistant's own judgment of its code

Yes, a CI run is more reliable because it does not depend on the assistant's opinion of its own work. In one case, a Ruby fix and its tests were written by a coding assistant with no Ruby installed locally; the first CI run failed, and the fault turned out to be in the test itself, not the code, which CI caught without the assistant having to self-assess.

_Developers deciding how much to trust agent-written tests can follow CI-first workflows on daily.dev._

## Community discussion

Top comments from developers on daily.dev.

**@diyweb** · 1 upvotes

> This matches what we have seen with content work too, not only code: a style rule in prose gets followed most of the time, while a small lint script that checks banned words or sentence length gets followed every time. Keeping the Markdown for intent and context and the scripts for enforcement seems like the right split. Do you version the scripts with the repo the agent works on, or keep them in a separate place it cannot edit?

**@rappayne** · 1 upvotes

> Nice article. Good summary. Overkill solution, IMO. Use sparingly.

**@sunnatulla\_dev** · 1 upvotes

> For the sentence-length case, if the agent is Claude Code you can move the check from "after the fact" to "before it's done". A Stop hook gets the final reply as last_assistant_message on stdin, and if the script exits 2 the agent isn't allowed to stop, it gets the stderr back and has to rewrite.
>
> ```json
>
> { "hooks": { "Stop": [ { "hooks": [ { "type": "command", "command": "python3 .claude/hooks/check-reply.py" } ] } ] } }
>
> ```
>
> The script splits the reply into sentences, prints the ones over 20 words to stderr and exits 2, otherwise 0. Check stop_hook_active in the input and exit 0 when it's...

**@paoloap** · 0 upvotes

> our reply checker blocked 120 replies in a few days, 89 of them false. a script that cries wolf gets routed around, so test it on known answers.

## Similar posts on daily.dev

- [Stop writing rules in AGENTS.md: use agent hooks and nano-staged instead—Martian Chronicles, Evil Martians’ team blog](https://daily.dev/posts/stop-writing-rules-in-agents-md-use-agent-hooks-and-nano-staged-instead-martian-chronicles-evil-ma-da7slckod) · Martian Chronicles · 0 upvotes · 0 comments
- [AGENTS.md vs. skills: How to steer a coding agent](https://daily.dev/posts/agents-md-vs-skills-how-to-steer-a-coding-agent-w1duhdmys) · CircleCI · 1 upvotes · 0 comments
- [Tell the Agent to Write Its Scripts in Ruby](https://daily.dev/posts/tell-the-agent-to-write-its-scripts-in-ruby-9gocdylkx) · RUBYLAND · 0 upvotes · 0 comments
- [Write agent instructions that explain the decision](https://daily.dev/posts/write-agent-instructions-that-explain-the-decision-5djfm6d1d) · Flavio Copes · 6 upvotes · 1 comments

---

Tags: [#ai](https://daily.dev/tags/ai), [#devops](https://daily.dev/tags/devops), [#ai-agents](https://daily.dev/tags/ai-agents), [#devtools](https://daily.dev/tags/devtools), [#productivity](https://daily.dev/tags/productivity), [#cicd](https://daily.dev/tags/cicd), [#claude-code](https://daily.dev/tags/claude-code)

[View this post on daily.dev](https://daily.dev/posts/don-t-write-markdown-files-for-your-coding-agent-write-scripts--giqm4p76d)

```json
{"@context":"https://schema.org","@graph":[{"@type":"Organization","@id":"https://daily.dev/#organization","name":"daily.dev","url":"https://daily.dev","logo":{"@type":"ImageObject","url":"https://daily.dev/apple-touch-icon.png","width":180,"height":180},"sameAs":["https://twitter.com/dailydotdev","https://github.com/dailydotdev","https://www.linkedin.com/company/daily-dev-ltd"]},{"@type":"WebSite","@id":"https://daily.dev/#website","url":"https://daily.dev","name":"daily.dev","publisher":{"@id":"https://daily.dev/#organization"},"potentialAction":{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https://daily.dev/search?q={search_term_string}"},"query-input":"required name=search_term_string"}}]}
{"@context":"https://schema.org","@type":"TechArticle","headline":"Don't Write Markdown Files for Your Coding Agent. Write Scripts.","url":"https://daily.dev/posts/don-t-write-markdown-files-for-your-coding-agent-write-scripts--giqm4p76d","mainEntityOfPage":{"@type":"WebPage","@id":"https://daily.dev/posts/don-t-write-markdown-files-for-your-coding-agent-write-scripts--giqm4p76d"},"datePublished":"2026-11-05T23:30:33.149Z","dateModified":"2026-11-05T23:55:56.162Z","description":"Markdown instruction files for coding agents are recommendations, not constraints. The fix is to translate preferences into deterministic scripts: lint.sh,...","image":"https://media.daily.dev/image/upload/f_auto,q_auto/v1/posts/c5e508eea3b70d81d2dfe089f5c5271b?_a=AQAEuop","thumbnailUrl":"https://media.daily.dev/image/upload/f_auto,q_auto/v1/posts/c5e508eea3b70d81d2dfe089f5c5271b?_a=AQAEuop","isAccessibleForFree":true,"articleSection":"DEV","inLanguage":"en","publisher":{"@type":"Organization","name":"daily.dev","url":"https://daily.dev","logo":{"@type":"ImageObject","url":"https://daily.dev/apple-touch-icon.png","width":180,"height":180}},"author":{"@type":"Organization","name":"DEV","logo":"https://media.daily.dev/image/upload/t_logo,f_auto/v1/logos/devto","url":"https://daily.dev/sources/devto"},"commentCount":4,"discussionUrl":"https://daily.dev/posts/don-t-write-markdown-files-for-your-coding-agent-write-scripts--giqm4p76d","interactionStatistic":[{"@type":"InteractionCounter","interactionType":{"@type":"LikeAction"},"userInteractionCount":22},{"@type":"InteractionCounter","interactionType":{"@type":"CommentAction"},"userInteractionCount":4}],"keywords":"ai,devops,ai-agents,devtools,productivity,cicd,claude-code","timeRequired":"PT5M"}
{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://daily.dev"},{"@type":"ListItem","position":2,"name":"DEV","item":"https://daily.dev/sources/devto"},{"@type":"ListItem","position":3,"name":"Don't Write Markdown Files for Your Coding Agent. Write Scripts."}]}
{"@context":"https://schema.org","@type":"WebPage","@id":"https://daily.dev/posts/don-t-write-markdown-files-for-your-coding-agent-write-scripts--giqm4p76d","comment":[{"@type":"Comment","text":"This matches what we have seen with content work too, not only code: a style rule in prose gets followed most of the time, while a small lint script that checks banned words or sentence length gets followed every time. Keeping the Markdown for intent and context and the scripts for enforcement seems like the right split. Do you version the scripts with the repo the agent works on, or keep them in a separate place it cannot edit?","datePublished":"2026-11-08T14:03:47.107Z","url":"https://daily.dev/posts/GIqM4P76d#c-PJ0lv8qi2","author":{"@type":"Person","name":"DiyWeb","url":"https://daily.dev/diyweb","image":"https://media.daily.dev/image/upload/s--dgS6jDeN--/f_auto/v1790879420/avatars/avatar_774zDwMaRTNS1fv5OKStX?_a=BAMAMicg0"},"interactionStatistic":{"@type":"InteractionCounter","interactionType":{"@type":"LikeAction"},"userInteractionCount":1}},{"@type":"Comment","text":"Nice article. Good summary. Overkill solution, IMO. Use sparingly.","datePublished":"2026-11-06T17:31:08.309Z","url":"https://daily.dev/posts/GIqM4P76d#c-dHPbC7dAq","author":{"@type":"Person","name":"Rap Payne","url":"https://daily.dev/rappayne","image":"https://avatars.githubusercontent.com/u/1122906?v=4"},"interactionStatistic":{"@type":"InteractionCounter","interactionType":{"@type":"LikeAction"},"userInteractionCount":1}},{"@type":"Comment","text":"For the sentence-length case, if the agent is Claude Code you can move the check from “after the fact” to “before it’s done”. A Stop hook gets the final reply as last_assistant_message on stdin, and if the script exits 2 the agent isn’t allowed to stop, it gets the stderr back and has to rewrite.\n\n{ \u0026quot;hooks\u0026quot;: { \u0026quot;Stop\u0026quot;: [ { \u0026quot;hooks\u0026quot;: [ { \u0026quot;type\u0026quot;: \u0026quot;command\u0026quot;, \u0026quot;command\u0026quot;: \u0026quot;python3 .claude/hooks/check-reply.py\u0026quot; } ] } ] } }\n\n\nThe script splits the reply into sentences, prints the ones over 20 words to stderr and exits 2, otherwise 0. Check stop_hook_active in the input and exit 0 when it’s true, or a reply it can’t fix keeps it looping. I ran the script against sample hook payloads, not a full session, so treat it as a sketch.\nSame idea covers the “agent can skip a local hook” part: a PreToolUse hook on Bash that denies anything with --no-verify. CI as the final gate is still the right call, this just makes the local loop cheaper.","datePublished":"2026-11-08T09:08:41.642Z","url":"https://daily.dev/posts/GIqM4P76d#c-IXdf4MC2c","author":{"@type":"Person","name":"Sunnatulla E.","url":"https://daily.dev/sunnatulla_dev","image":"https://lh3.googleusercontent.com/a/ACg8ocJo-F7wmmAt8NSb8q7sICb2AcjYKKjZ4SLvvn97P34Ovt-DjA=s96-c"},"interactionStatistic":{"@type":"InteractionCounter","interactionType":{"@type":"LikeAction"},"userInteractionCount":1}},{"@type":"Comment","text":"our reply checker blocked 120 replies in a few days, 89 of them false. a script that cries wolf gets routed around, so test it on known answers.","datePublished":"2026-11-10T04:11:37.145Z","url":"https://daily.dev/posts/GIqM4P76d#c-jSKVKjrCh","author":{"@type":"Person","name":"Paolo Perrone","url":"https://daily.dev/paoloap","image":"https://lh3.googleusercontent.com/a/AGNmyxaOowFqs19Msmo4AtbOanvSwkOb705dhJ-u3fFQ0Nw=s96-c"}}]}
{"@context":"https://schema.org","@type":"FAQPage","@id":"https://daily.dev/posts/don-t-write-markdown-files-for-your-coding-agent-write-scripts--giqm4p76d#faq","mainEntity":[{"@type":"Question","name":"why does my coding agent ignore the rules in my AGENTS.md or CLAUDE.md file","acceptedAnswer":{"@type":"Answer","text":"Markdown instructions are treated as recommendations, not constraints, because the agent has to parse, balance, and exercise judgment over them rather than follow a strict rule. Vague directives like 'use the existing logging conventions' or 'use small functions' leave room for the agent to rationalize deviations, such as assuming conflicting code means the docs are outdated. Developers tightening agent instructions can compare approaches to deterministic tooling on daily.dev."}},{"@type":"Question","name":"how do you make an AI coding agent follow a style rule reliably","acceptedAnswer":{"@type":"Answer","text":"Convert the rule into a script with a pass or fail exit condition instead of a prose instruction. One example turned the ASD-STE100 plain-English rule 'keep sentences to 20 words or fewer' into a script constant MAX_SENTENCE = 20, run through a Claude Code Stop hook after each reply, looping the agent back for another try on failure. Anyone scripting guardrails for agent output can track these patterns on daily.dev."}},{"@type":"Question","name":"should I trust CI test failures over my AI coding assistant's own judgment of its code","acceptedAnswer":{"@type":"Answer","text":"Yes, a CI run is more reliable because it does not depend on the assistant's opinion of its own work. In one case, a Ruby fix and its tests were written by a coding assistant with no Ruby installed locally; the first CI run failed, and the fault turned out to be in the test itself, not the code, which CI caught without the assistant having to self-assess. Developers deciding how much to trust agent-written tests can follow CI-first workflows on daily.dev."}}]}
```