The AI=true Anti-Pattern: Why Separating Human and AI Workflows Hurts Everyone

The software development landscape is undergoing a subtle but significant transformation. As AI coding assistants become increasingly sophisticated, developers are discovering new ways to integrate these tools into their workflows. However, a concerning pattern has emerged: the creation of parallel systems that cater exclusively to AI agents while leaving human developers behind.

The Rise of AI-Only Workflows

The evidence of this trend is everywhere. Developers are writing comprehensive documentation, but instead of placing it in traditional README files where both humans and machines can find it, they're creating specialized AGENTS.md or copilot-instructions.md files. They're building valuable automation tools, but exposing them only through MCP (Model Context Protocol) servers rather than command-line interfaces. They're enhancing test output and command-line tools, but gating these improvements behind AI-specific flags like AI=true.

This approach seems logical at first glance. AI agents have different needs than human developers—they benefit from structured documentation, predictable interfaces, and specialized tooling. But this segregation creates more problems than it solves.

Why Documentation Belongs in README.md

Good documentation serves both humans and AI equally well. When you write clear, concise documentation that explains how to use a tool or library, you're creating value for everyone who interacts with your code. AI agents benefit from well-structured information just as much as human developers do.

The context window limitations that affect AI agents also apply to human cognition. A developer scanning through documentation needs the same kind of concise, relevant information that an AI agent requires. The difference is that humans can ask questions, explore related topics, and use their intuition to fill gaps—but that doesn't mean we should make their job harder.

Placing documentation in AGENTS.md files creates discoverability issues. New team members won't know to look there. External contributors won't find it. The conventions for these specialized files are still evolving and often vendor-specific, making them unreliable dependencies. Meanwhile, README.md remains the universal standard that everyone understands.

The Power of Unified Tool Interfaces

Command-line tools and APIs represent the sweet spot for interoperability between humans and AI. These interfaces are text-based, composable, and scriptable—qualities that make them equally accessible to both developers and AI agents. When you create a command-line tool, you're building something that can be used in shell scripts, automated workflows, and AI-driven development processes.

MCP servers, while promising, haven't yet demonstrated clear advantages over traditional command-line tools. In fact, they often introduce new problems. One common scenario involves tools that take a long time to execute without producing output, causing AI agents to terminate them prematurely. This same issue frustrates human developers who wonder whether a command is hanging or simply processing.

Mental Overload Affects Everyone

The context window limitations that constrain AI agents also affect human developers. When a tool produces excessive output, it overwhelms both the AI's context window and the developer's ability to parse relevant information. When a tool hangs without feedback, both AI agents and humans are likely to terminate it prematurely.

The solution isn't to create separate tools for different users—it's to design better tools that work well for everyone. Tools that execute quickly, produce concise output, and provide clear feedback benefit both humans and AI. Tools that follow Unix philosophy principles of doing one thing well and working well with others serve all users equally.

APIs as the Foundation

When building new internal tools, the most future-proof approach is to start with an API. This creates a solid foundation that can be exposed through multiple interfaces: a command-line tool for developers, a web interface for interactive use, and programmatic access for AI agents. Each interface serves its audience while sharing the same underlying functionality.

This approach prevents the scope creep that often plagues web applications while ensuring that the core functionality remains accessible to all users. Developers can script and automate workflows that you never anticipated. AI agents can integrate your tools into their workflows seamlessly. Everyone benefits from a unified, well-designed interface.

The Cost of Segregation

Creating separate workflows for humans and AI agents introduces significant maintenance overhead. You're now maintaining multiple code paths, multiple documentation sets, and multiple user experiences. When you fix a bug or add a feature, you need to update both systems. When you change an API, you need to update both interfaces.

More importantly, you're creating a cognitive burden for your team. Developers need to remember which tools work for which users. They need to context-switch between different interfaces and workflows. They need to maintain expertise in multiple systems that essentially do the same thing.

Practical Recommendations

Instead of segregating workflows, focus on creating unified experiences that work well for everyone:

Documentation: Place it in README.md files where both humans and AI can find it. Use clear structure, concise language, and relevant examples. Include "See README.md" references where appropriate rather than duplicating information.

Tool Interfaces: Prefer command-line tools and APIs over GUI applications and MCP servers. These interfaces are more composable, more scriptable, and more accessible to both humans and AI.

Output Design: Design tools with limited output in mind. Use --quiet flags to reduce verbosity, but aim for sensible defaults that work for most use cases. Provide clear progress indicators for long-running operations.

Parameter Design: Avoid flags that segregate workflows between humans and AI. Instead of AI=true, use --quiet or --verbose. Design tools that work well in both interactive and automated contexts.

API-First Development: When building new tools, start with an API. Then create command-line wrappers and web interfaces as needed. This ensures that the core functionality remains accessible to all users while providing appropriate interfaces for different use cases.

The goal isn't to eliminate specialization entirely—some tools will always be more suited to human interaction, others to AI automation. But the default should be unified interfaces that work well for everyone, with specialization as the exception rather than the rule.

The Future of Development Workflows

The most successful development tools of the future will be those that seamlessly serve both human developers and AI agents. They'll have clear, consistent interfaces that are easy to document and easy to automate. They'll produce output that's useful whether you're reading it on a terminal or parsing it in a context window.

This isn't just about convenience—it's about creating sustainable, maintainable systems that can evolve with our changing development practices. As AI becomes more integrated into our workflows, we need tools that can adapt without requiring complete rewrites or parallel implementations.

The AI=true anti-pattern represents a short-term solution to a long-term problem. It's tempting to create separate systems for different users, but this approach creates more complexity than it solves. Instead, we should focus on building better tools that work well for everyone—tools that recognize the fundamental similarities between human and AI workflows rather than their differences.

In the end, good software design principles apply regardless of who's using the software. Clear interfaces, concise documentation, and thoughtful user experience benefit everyone. By focusing on these universal principles rather than user-specific optimizations, we can create development tools that serve us all well into the future.