<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Enes Bulut on Medium]]></title>
        <description><![CDATA[Stories by Enes Bulut on Medium]]></description>
        <link>https://medium.com/@enes-bulut?source=rss-7dd811e45fcc------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*c0LBqSACLVJ-tP_b43bzDQ.png</url>
            <title>Stories by Enes Bulut on Medium</title>
            <link>https://medium.com/@enes-bulut?source=rss-7dd811e45fcc------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Fri, 20 Nov 2026 20:54:04 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@enes-bulut/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Wise Coding: A Methodology for Sustainable, Production-Grade Agentic Development]]></title>
            <link>https://enes-bulut.medium.com/wise-coding-a-methodology-for-sustainable-production-grade-agentic-development-dc1b9275187b?source=rss-7dd811e45fcc------2</link>
            <guid isPermaLink="false">https://medium.com/p/dc1b9275187b</guid>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[developer-tools]]></category>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[software-development]]></category>
            <category><![CDATA[coding]]></category>
            <dc:creator><![CDATA[Enes Bulut]]></dc:creator>
            <pubDate>Tue, 17 Mar 2026 17:17:06 GMT</pubDate>
            <atom:updated>2026-03-17T17:17:06.939Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*RWmjPExFhvR2JnYIAM-ANA.png" /></figure><blockquote><strong>TL;DR:</strong> Over 60,000 repositories now contain context files for AI coding agents. A recent ETH Zurich study found that LLM-generated context files make agents worse while developer-written ones provide marginal gains. The problem is not context files themselves. The problem is that nobody has a methodology for writing them, maintaining them, or connecting them to how teams actually work. Here comes <strong>Wise Coding</strong>. A structured approach to managing repository knowledge so that both humans and AI agents produce consistent, compliant, and sustainable software.</blockquote><p>I have been working on this topic for the last seven months. The idea started with a simple observation. Teams adopting AI coding agents were getting impressive speed but losing consistency, compliance, and institutional knowledge in the process. What if you could keep the speed of agentic development while making the output enterprise-grade from the start? The term wise coding came from that tension and from a conviction that applying docs-as-code methodology to agentic development could bridge the gap between speed and governance.</p><p>Since then, the landscape has changed significantly. Context files went from an early-adopter experiment to mainstream practice. Sixty thousand repositories now contain some form of AGENTS.md or CLAUDE.md. Researchers started measuring whether they actually help. And the real problem became clear. It is not about whether to add context. It is about how to manage it without creating a new kind of technical debt.</p><h3><strong>The Context Mess</strong></h3><p>By the second half of 2025, the industry had largely converged on one idea. AI coding agents need context. You cannot point Claude Code at a repository and expect it to know your naming conventions, your deployment constraints, or why you chose Polars over Pandas three months ago. The solution was simple. Write a markdown file. Call it CLAUDE.md or AGENTS.md or .cursorrules. Put it in the root of your repo. Tell the agent what it needs to know.</p><p>Tens of thousands of repositories did exactly that.</p><p>Then, in February 2026, researchers at ETH Zurich published “Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?” It was the first rigorous study on whether these files actually work. They built AGENTbench, a benchmark of 138 real-world coding tasks from repositories that already had developer-written context files. They tested four coding agents including Claude Code, Codex, and Qwen Code across three conditions. No context file at all. An LLM-generated context file. A human-written context file.</p><p>The key finding was this. All context files consistently increase the number of steps required to complete tasks. LLM-generated context files have a marginal negative effect on task success rates. But developer-written context files provide a marginal performance gain. The agents followed the instructions faithfully. When those instructions were thorough but unnecessary for the task at hand, the agents explored more, tested more, and spent more tokens without improving outcomes.</p><p>This is exactly where wise coding enters the picture. The study confirms that developer-written context works better than auto-generated context. But it also reveals that dumping everything into one file is not the answer. What matters is giving the agent the right context for the right task at the right time.</p><p>Addy Osmani put it well. The question is not whether to have a context file. The question is what earns a line in it.</p><p>I would go further. The question is not about one file at all. It is about methodology.</p><h3><strong>From Vibe Coding to Wise Coding</strong></h3><p>About a year ago, Andrej Karpathy introduced the term vibe coding. You describe what you want in natural language, accept the code the AI generates, and iterate based on what happens. For personal projects and rapid prototypes, this produces working software faster than anything before it.</p><p>But vibe coding does not scale, and it definitely does not comply with enterprise standards, security policies, or regulatory requirements. AI models are trained on data with a cutoff that can lag months behind the present. Once deployed they are static. Even more important, they have no awareness of your enterprise standards and rules. They do not know your approved dependency list, your authentication patterns, or the architectural decisions your team made last quarter.</p><p>The question was never whether AI could write software. It clearly can. The question is whether that software is fit for the environments where failures have real consequences. That is the gap wise coding exists to close. The goal is to bring the speed and accessibility of vibe coding into the enterprise, with the governance and structure that production systems demand.</p><h3><strong>Why Files Fail Without Method</strong></h3><p>Every article about CLAUDE.md or AGENTS.md treats the problem as a writing problem. <em>“Keep it minimal.” “Only include what the agent cannot infer.” “Do not let LLMs generate your context file.” </em>This advice is correct but insufficient. It is like telling someone to “write clean code” without teaching them version control, code review, or testing. Individual tips help individual developers. What teams need is a repeatable method.</p><p>Here is what I see teams doing right now. A senior engineer writes a CLAUDE.md one afternoon. It captures their mental model of the project. It works well for a few weeks. Then a new feature changes the architecture. Nobody updates the file. A second developer adds .cursorrules for a different tool with slightly different conventions. A third person adds a <em>docs/</em> folder with design decisions that nothing references. The context is scattered across files that do not talk to each other, maintained by nobody, and slowly drifting from the truth.</p><p>Context files are an ingredient. What is missing is the recipe.</p><h3><strong>What Wise Coding Actually Is</strong></h3><p>Wise Coding is a methodology for organizing, maintaining, and evolving repository knowledge so that it serves both human developers and AI agents across the entire lifecycle of a project.</p><p>It rests on three principles.</p><p><strong>First, context must be structured, not dumped.</strong> A single monolithic file is the wrong unit of organization. Different types of knowledge have different audiences, different update frequencies, and different levels of importance. Project architecture, coding standards, dependency policies, and design decisions belong in separate, purpose-built documents that reference each other. When an agent needs to generate a REST endpoint, it reads the API guidelines and the dependency policy. It does not read a monolithic overview of the entire project. The total documentation across all files can be extensive, but the agent only loads what is relevant to the task it is performing right now.</p><p><strong>Second, what AI agents do must be documented the same way code changes are documented.</strong> If a developer makes an architectural decision, they write an Architecture Decision Record. If an AI agent generates a service layer or refactors a module, that work should be documented too. Not in a chat log that disappears when the session ends, but in the repository. Version-controlled. Reviewable. Available to the next person or agent who touches that code.</p><p><strong>Third, knowledge must be sustainable.</strong> The real test of documentation is not whether it helps the person who wrote it. It is whether it helps the person who arrives six months later and has never spoken to anyone on the original team. In a world where AI agents are the primary code generators, that new arrival might be orchestrating agents rather than writing code directly. If the repository does not contain enough structured knowledge for that developer to direct agents effectively, every productivity gain from AI disappears during onboarding.</p><p>These principles naturally lead to a docs-as-code approach. Documentation lives in the repository alongside the code, follows the same version control workflows, goes through the same review processes, and evolves with every pull request. This is not a new idea in software engineering, but wise coding applies it specifically to the challenge of AI-assisted development. The documentation is not just for humans anymore. It is simultaneously the context layer that AI agents read before generating a single line of code.</p><p>The core insight behind wise coding is a sentence I keep coming back to. Knowledge lives with your code, not with your people. When that knowledge is structured, current, and machine-readable, you do not lose velocity when someone leaves the team. You do not lose consistency when a new agent joins the workflow. You do not lose compliance when the auditor asks how a decision was made.</p><h3><strong>The Repository as a Knowledge System</strong></h3><p>Here is what a wise coding repository looks like in practice. This is just an example. You can add your company’s architecture framework documents, domain-specific policies, or modify the structure to fit your needs.</p><pre>project-root/<br>├── AGENTS.md              # Root routing file: global rules and pointers<br>├── CLAUDE.md              # Claude Code specific supplements<br>├── GEMINI.md              # Gemini CLI specific supplements<br>├── docs/<br>│   ├── AGENTS.md          # Documentation-level routing for agents<br>│   ├── CLAUDE.md          # Claude Code supplements for docs context<br>│   ├── GEMINI.md          # Gemini CLI supplements for docs context<br>│   ├── CHANGELOG.md       # Tracks all changes including agent work<br>│   ├── project/<br>│   │   ├── PROJECT_RULES.md        # Project-specific rules written by the team<br>│   │   ├── PROJECT_ARCHITECTURE.md # Project system design and components<br>│   │   └── TEST_SCENARIOS.md       # Domain-specific test scenarios<br>│   ├── standards/<br>│   │   ├── AGENTS.md<br>│   │   ├── CLAUDE.md<br>│   │   ├── GEMINI.md<br>│   │   ├── java-style-guide.md<br>│   │   ├── api-design-guidelines.md<br>│   │   └── testing-standards.md<br>│   ├── security/<br>│   │   ├── AGENTS.md<br>│   │   ├── CLAUDE.md<br>│   │   ├── GEMINI.md<br>│   │   ├── security-policy.md<br>│   │   └── dependency-policy.md<br>│   ├── architecture/<br>│   │   ├── AGENTS.md<br>│   │   ├── CLAUDE.md<br>│   │   ├── GEMINI.md<br>│   │   ├── ARCHITECTURE.md    # Enterprise architecture patterns<br>│   │   └── decisions/<br>│   │       ├── 001-auth-approach.md<br>│   │       ├── 002-database-choice.md<br>│   │       └── 003-api-versioning.md<br>│   ├── external-guides/<br>│   │   ├── spring-boot-4-guide.md<br>│   │   └── oauth2-reference.md<br>│   ├── source-docs/<br>│   │   └── [mirrors source structure]<br>│   └── skills/<br>│       ├── openai-gpt-5-4-upgrade.md<br>│       └── canvas-design.md<br>├── .github/<br>│   └── workflows/<br>│       └── doc-check.yml  # CI step: validate doc references<br>└── src/<br>    └── [source code]</pre><p>CLAUDE.md and GEMINI.md are optional. They exist for teams using IDEs or CLI tools that load these files by default. Claude Code reads CLAUDE.md automatically. Gemini CLI reads GEMINI.md. If you use tools that support the more generic AGENTS.md format, you may not need the tool-specific files at all. They supplement the shared context with behavioral adjustments for each tool.</p><p>The <em>docs/project/</em> folder holds everything specific to this particular project. PROJECT_RULES.md captures conventions that do not fit neatly into the standards or security documents. Things like naming patterns unique to this project, deployment quirks, or integration constraints with external systems. PROJECT_ARCHITECTURE.md describes the project’s own system design and component relationships, distinct from the enterprise-wide patterns in <em>docs/architecture/</em>. TEST_SCENARIOS.md defines domain-specific test scenarios that agents should run after generating code. These are developer-written files that evolve with the project.</p><p>Several things to notice about this structure.</p><p><strong>AGENTS.md files are routing files, not instruction manuals.</strong> The root AGENTS.md contains the rules that apply globally and pointers to the documents that hold the actual knowledge. We keep it short, but not artificially constrained to a specific line count. What matters is that every line earns its place. Subdirectories can have their own AGENTS.md files too, along with corresponding CLAUDE.md and GEMINI.md files to cover all agentic coding tools. The <em>standards/</em> folder has them. The <em>security/</em> folder has them. The <em>architecture/</em> folder has them. When a coding agent enters a specific folder, it reads the local routing file to understand how to operate within that context. This way the whole repository is covered by structured guidance, but no single agent session is overloaded with irrelevant information. The agent reads the root-level rules plus only the context relevant to where it is working.</p><p><strong>Standards, security, and architecture each have their own space.</strong> Coding standards live in <em>docs/standards/</em>. Security policies live in <em>docs/security/</em>. Architectural documentation and design decisions live in <em>docs/architecture/</em>. This separation matters because an agent working on API design reads the standards folder. An agent evaluating a dependency reads the security folder. An agent making a structural change reads the architecture folder and its decisions. No agent reads all of them at once unless the task genuinely requires it.</p><p><strong>Design decisions live under architecture.</strong> Each decision record answers what was decided, why it was decided, and what alternatives were considered. These records are not just for humans reviewing the history of the project. They are for AI agents that need to understand constraints. When an agent reads that your team chose PostgreSQL over MongoDB because of transactional requirements, it will not suggest a document database for your next feature.</p><p><strong>External guides bring outside knowledge into your repository.</strong> The <em>docs/external-guides/</em> folder contains curated documents from outside your organization. Framework guidelines, security standards, API references from third-party vendors. Instead of relying on the agent’s training data for this knowledge, you provide the specific versions and interpretations that your team has adopted. This keeps the agent aligned with your actual technology choices rather than generic best practices.</p><p><strong>Source documentation mirrors the source code.</strong> This is a key part of the methodology. Under <em>docs/source-docs</em>, the documentation follows the exact same path structure as the source code under <em>src/</em>. When an AI agent generates or modifies a source file, it also generates or updates the corresponding documentation at the mirrored path under <em>docs/source-docs/</em>. The developer reviews both the code and the documentation before committing. This is not a changelog or a log. It is living, structured documentation that stays synchronized with the code it describes. When a new developer or a new agent needs to understand what a module does and why it was built that way, the answer is sitting right next to the code in a predictable location.</p><p><strong>Skills provide reusable task templates for agents.</strong> The <em>docs/skills/</em> folder contains markdown files that agents load on demand for specific tasks. A skill like openai-gpt-5-4-upgrade.md is used when an agent needs up-to-date OpenAI documentation, help choosing the latest model, or GPT-5.4 upgrade and prompt-migration guidance. A skill like canvas-design.md is used when an agent needs to create visual designs, posters, or static artwork as .png or .pdf documents following a design philosophy. You can add your favorite skills here as your team discovers repeatable workflows worth capturing. If your tooling supports skills natively, you can integrate these files with your tooling too. If it does not, they still work as referenced documents that agents read when performing specific tasks.</p><h3><strong>The CHANGELOG as a Record of All Work</strong></h3><p>CHANGELOG.md tracks every significant change to the project, whether made by a human or an AI agent. When an agent refactors a payment service or introduces a new module, the entry captures what changed, which files were affected, and what review decisions were made.</p><pre>## [2026–03–17] Payment Service Multi-Currency Support<br>**Agent:** Claude Code (Opus 4.6)<br>**Requested by:** @developer-name<br>**PR:** #847<br><br>### Changes<br>- Extracted currency conversion into standalone module<br>- Added exchange rate caching layer with 5-minute TTL<br>- Updated payment endpoints to accept currency parameter<br>- Generated 23 unit tests for conversion edge cases<br><br>### Review Notes<br>- TTL changed from 15 to 5 minutes per compliance requirement<br>- Documentation synced at docs/source-docs/com/example/payment/</pre><p>This is version-controlled and searchable. When a new developer asks why the payment service has its own currency module instead of using the shared library, the answer is in the repository. Not in someone’s memory. Not in a Slack thread from three months ago.</p><p>More importantly, when the next AI agent touches the payment service, it can read this entry and understand the constraints and decisions that shaped the current code. Context is not just what the codebase looks like now. Context is how it got here.</p><h3>Closing the Onboarding Gap</h3><p>There is a specific problem wise coding solves that I have not seen addressed anywhere else.</p><p>The developers arriving at companies today are not just writing code. They are orchestrating AI agents that write code. Their onboarding experience is fundamentally different from what it was two years ago. They need to learn not only the codebase but also how to direct agents within that codebase effectively. Which context files exist. What the conventions are. Where the boundaries are between what the agent can decide and what requires human judgment.</p><p>Without a methodology, each new developer reinvents this understanding through trial and error. They prompt the agent, get unexpected results, manually correct, learn a constraint the hard way, and eventually build a mental model of the project that lives entirely in their head. Just like it lived in the previous developer’s head.</p><p>Wise coding breaks this cycle. When the repository contains structured context, documented decisions, and synchronized source documentation, a new developer can direct an agent effectively on day one. Not because the developer already knows the codebase, but because the repository contains enough structured knowledge to guide both the developer and the agent from the start.</p><p>Consider the practical sequence. A new developer gets a task. They read AGENTS.md, which points them to the relevant docs. The agent reads the same docs. The developer prompts the agent with the task. The agent generates code that follows the architecture, uses approved dependencies, and respects documented constraints. The developer reviews both the code and the generated documentation. The PR passes CI, which includes a documentation consistency check. The CHANGELOG captures what was done and why.</p><p>Every step is traceable. Every decision is recorded. The next developer who arrives will find the same structured knowledge, plus everything that happened since the last person joined.</p><h3>What Does Not Change</h3><p>Wise coding does not change what humans are responsible for. Humans still review every line of AI-generated code, still make architectural decisions, and still own the repository and its documentation. None of that goes away.</p><p>What changes is the infrastructure around that responsibility. Instead of relying on tribal knowledge, code reviews catch structural issues because the reviewer can check the output against written standards. Instead of discovering constraints through production incidents, agents read them from documentation before generating a single line. Instead of onboarding taking weeks of shadowing and asking questions, the repository provides the answers directly.</p><p>Let AI handle what machines are good at. Keep humans where judgment matters. That is the entire design principle.</p><h3>The Maintenance Question</h3><p>The obvious objection is maintenance. “I can barely keep my README up to date. Now you want me to maintain decision records, source documentation, and structured context?”</p><p>This objection treats documentation as overhead. Wise coding treats it as output.</p><p>When an AI agent generates code, it also generates the corresponding source documentation. The developer reviews both, and that review covers documentation quality with the same rigor as code quality. Vague or verbose generated docs get edited or rejected, just like vague or verbose generated code. That is one review cycle, not two separate maintenance tasks. When a team makes a design decision during a PR review, capturing that decision in a record is five minutes of writing that saves hours of future confusion. When a coding standard changes, updating one document is faster than correcting every agent’s output for the next month.</p><p>The CI pipeline validates it. Add a step that checks whether referenced documents exist, whether source-docs are present for new or modified source files, and whether the routing file points to real paths. Documentation rot happens when nobody checks. Automation checks.</p><p>For teams already running hooks and skills in Claude Code or Cursor, this becomes even more natural. A pre-commit hook can verify that any PR touching source files includes corresponding documentation updates. A post-task hook can generate documentation templates automatically. Skills can encode the entire workflow for common tasks so that agents produce both code and documentation in a single pass. The methodology adapts to the tooling, not the other way around.</p><h3>The Reference Repository</h3><p>To help teams get started, a reference implementation is available on GitHub that demonstrates the complete methodology. It includes AGENTS.md routing files, CLAUDE.md and GEMINI.md supplements, a full docs directory with coding standards, security policies, architecture decision records, source-docs synchronization, external guides, and CI workflow validation. Everything discussed in this article has a working example in the repository.</p><p><strong>Repository:</strong> <a href="https://github.com/wise-coding/wise-coding-reference">github.com/wise-coding/wise-coding-reference</a></p><p><em>Contributions are welcome. The methodology improves as more teams adopt it and share what works in their environments. If you have a different approach that fits within the wise coding philosophy, open a PR. The repository itself follows docs-as-code, so contributing is as simple as editing a markdown file.</em></p><p><strong>Vibe coding proved that AI can write software. Wise coding is the discipline of making sure that software is fit for production.</strong></p><p><em>A patent application has been filed for the methodology to help ensure it remains available for community adoption and is not later restricted by third-party proprietary claims.</em></p><h3>References</h3><p>- Gloaguen, T., Mündler, N., Müller, M., Raychev, V., &amp; Vechev, M. (2026). “Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?” ETH Zurich. arXiv:2602.11988</p><p>- Osmani, A. (2026). “Stop Using /init for AGENTS.md.” addyosmani.com</p><p>- Anthropic (2026). “Effective Context Engineering for AI Agents.” anthropic.com/engineering</p><p>- Böckeler, B. (2026). “Context Engineering for Coding Agents.” martinfowler.com</p><p>- Yichao ‘Peak’ Ji (2025). “Context Engineering for AI Agents: Lessons from Building Manus.” manus.im</p><p>- Write the Docs. “Docs as Code.” writethedocs.org/guide/docs-as-code</p><p>- AGENTS.md specification. agents.md</p><p><em>You can reach me on </em><a href="https://www.linkedin.com/in/enesbulut"><em>LinkedIn</em></a><em> if you have anything to ask or share.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=dc1b9275187b" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>