{"slug": "artifact-rules-for-coding-agents", "title": "Artifact rules for coding agents", "summary": "A developer published a reusable instruction block for AGENTS.md, CLAUDE.md and system prompts that tells coding agents to write interfaces, docs, prompts and skills for their end reader rather than for the person who requested the work. The rules bar agents from leaking design decisions, rejected options, implementation details and requirement evidence into artifacts, require removing all traces of dropped features, and ask agents to prototype new user-facing text for approval before merging.", "body_md": "Coding agents tend to write their conversation into the product. Your decisions, their implementation details, notes proving a requirement was met, and instructions about options that were later dropped all end up in the app's interface, its docs, or in prompts and skills. The end user was never in that conversation, so all of it is noise to them, and you end up asking for each piece to be removed by hand.\n\nThis happens with every model family. Later agents tend to keep text they didn't write rather than question it, so it piles up.\n\nAppend the block below to whatever instructions your agents always receive, such as `AGENTS.md`, `CLAUDE.md` or a system prompt addition. If your setup runs subagents or workers, put it where they receive it too. Workers write most of the interfaces and docs.\n\n```\n## Writing artifacts\n\nAn artifact is anything you produce for people other than the person you're working with: an app's interface and its text, user docs, prompts, skills, config. Its reader wasn't in your conversation, so write only what that reader needs.\n\n- Write every artifact for its own reader, not for the person who asked for it. Leave out:\n  - decisions and the reasons for them;\n  - conversation history, and options that were rejected or removed;\n  - implementation details the reader doesn't need;\n  - evidence that a requirement was met.\n\n  For example, no \"data is preserved when you delete an item\" note because that was a design goal, and no counter added only to show that a feature works.\n- When something is removed, remove every trace of it, including any instruction that forbids it. For example, after dropping an export format, no \"don't use the old export format\" line remains in a prompt or doc.\n- In prompts, skills and other instructions, write a rule only for behavior its reader would actually show. When a rule is too broad, narrow it instead of adding an exception: \"ask before renaming user-visible commands\", not \"ask before renaming anything\" plus \"except internal names\".\n- In an interface, every element and string must help the end user act. Don't repeat what's already shown, such as a \"Healthy\" label beside a green status dot, and make the interface clear enough to need no instructions or hints.\n- Use the end user's words, not the names you used while building.\n- When a design changes, delete whatever in the affected area no longer serves the end user, whoever wrote it.\n- Show new interface elements and new user-facing text (labels, help text, notices) as a prototype, and get approval before merging them. Error messages and log lines don't need this.\n- Before reporting interface work, list each visible element and string in the changed area, with one line on why the end user needs it.\n```\n\n", "url": "https://wpnews.pro/news/artifact-rules-for-coding-agents", "canonical_source": "https://gist.github.com/oshinop/080aac7433f5bd0caafd26ea82f730f9", "published_at": "2026-11-21 06:00:18+00:00", "updated_at": "2026-11-21 08:14:17.194570+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "large-language-models"], "entities": [], "also_reported_by": [], "takeaway": "Appending a short 'writing artifacts' block to AGENTS.md, CLAUDE.md and subagent prompts stops coding agents from leaking design decisions, rejected options and requirement evidence into user-facing interfaces, docs and prompts.", "recommendation": {"advice": "Add the artifact-writing rules to every instruction file your coding agents and subagents read, and require a per-element justification list before merging interface changes.", "playbook": "coding-agents", "playbook_url": "https://wpnews.pro/playbooks/coding-agents"}, "alternates": {"html": "https://wpnews.pro/news/artifact-rules-for-coding-agents", "markdown": "https://wpnews.pro/news/artifact-rules-for-coding-agents.md", "text": "https://wpnews.pro/news/artifact-rules-for-coding-agents.txt", "jsonld": "https://wpnews.pro/news/artifact-rules-for-coding-agents.jsonld"}}