Every developer working with LLM-based agents has encountered the same friction point. You prompt an agent to generate a technical specification or a project plan, and it returns a visually stunning markdown table. It looks professional at first glance, but the moment you need to edit a single cell or expand a requirement, the formatting collapses. Worse, the prose often suffers from a distinct, sterile quality—what is known in the Korean community as translation-ese—where the logic is sound but the phrasing feels like a machine mimicking a human. This tension between visual polish and functional utility has become a bottleneck for teams trying to scale their AI agent orchestration.
The Shift from Visual Templates to Functional Logic
To address these systemic inefficiencies, the docs-system repository has been released as a specialized environment for researching AI agent instructions and managing configuration settings. Rather than providing a rigid framework or a plug-and-play application, docs-system functions as a methodology for how agents should handle documentation. The most striking decision in this system is the complete removal of markdown tables and fixed templates. The philosophy here is simple: the visual shape of a document is secondary to the actual presence and accuracy of the information it contains.
Central to this approach is the use-design-docs guide. This guide advocates for a writing style that maintains logical flow and comparative clarity without relying on grids. Instead of forcing information into a pre-defined table, the system encourages the use of selective subheadings, concise paragraphs, and lists based on the specific needs of the content. This ensures that the documentation remains readable and, more importantly, easily editable by both humans and agents.
In practice, the AI agent interacts with the `docs/designs/README.md` file to maintain a strict separation of concerns. The system mandates that requirements, research data, decisions, and execution plans be recorded in distinct sections. Under the use-design-docs skill, the agent defines the user's request and completion criteria as requirements. Any facts gathered from external sources or AI-driven analyses are relegated to separate research documents. Crucially, any item requiring a decision remains in a proposal state until explicitly approved. Only once a requirement is resolved and a decision is finalized does it move into the final execution plan. By forcing this separation, the system prevents a common AI failure mode where raw analysis data is mistaken for a final execution instruction.
The Two-Stage Filter Against Machine Prose
While structural organization solves the fragmentation problem, the quality of the language remains a challenge. AI agents often produce text that is grammatically correct but contextually unnatural. To solve this, docs-system introduces the use-words-review skill, a specialized pipeline designed to scrub Korean documentation of awkward phrasing before it is committed or shared externally.
This process does not rely on a single prompt but operates as a two-stage pipeline. First, a script scans the text to extract candidates for review—specifically targeting expressions likely to be translation-ese or paragraphs that are excessively long. This mechanical extraction acts as a high-pass filter, identifying potential problem areas without wasting agent resources on perfectly fine text. Once these candidates are identified, the main agent or a sub-agent performs a contextual analysis. The agent examines who the intended reader is, why the specific expression was used, and how the sentence relates to the surrounding text to determine if the phrasing is truly natural.
This architecture also addresses the critical issue of resource management. In earlier iterations, the system attempted to review every single chat response and progress notification, which led to an explosion in API call frequency and token consumption. The current version of docs-system optimizes this by excluding general chat and notifications from the review scope. The use-words-review skill now only triggers for the final output intended for storage or sharing, drastically reducing operational costs while maintaining high quality.
Perhaps the most significant design choice is the refusal to implement auto-correction. While it would be technically simple for the agent to rewrite the text automatically, use-words-review is designed only to analyze and report. It delivers the review results to the human user, who then makes the final decision on how to edit the text. This intentional friction prevents the AI from accidentally altering the technical meaning or nuance of a document during the polishing phase, ensuring that the human operator retains absolute authority over the final output.
By decoupling the role of the information from the template and separating the identification of linguistic errors from their correction, docs-system moves AI documentation away from superficial aesthetics and toward professional-grade utility.
