Contents (9)
- What document format is best for utilizing AI? (Write your thoughts directly and then use AI)
- The appearance of Agent Harness
- Utilizing AI leads to an explosive increase in document production.
- A document that is good for AI is different from a document that is good for humans.
- Markdown(.md) document file
- HTML(.html) document
- Ultimately, what matters is "who reads it."
- Ultimately, manage both with "Original" + "View"
- conclusion
What document format is best for utilizing AI? (Write your thoughts directly and then use AI)
The AGENTS.md file serves to provide core context to the AI Agent.
Developers make key information, such as behavioral rules, code style, and project structure, easy for AI agents to read.
In the early days when the use of AI began in earnest (though it seems like it has been about 1 to 2 years to call it the early days), it was built with the feeling of cramming basic prompts into a single AGENTS.md file. The results varied wildly depending on these prompts. Therefore, people tried to obtain better results by utilizing context engineering techniques.
However, problems soon emerged.
The Context Tolerance Problem in LLM Models
Token waste due to an overly long prompt
The phenomenon where result quality actually deteriorates when the Context is fully filled
The problem of becoming difficult to manage as the project grows larger
So people started creating concepts like SKILL and COMMAND.
I started separating the structure to inject the necessary context only when needed.
for example:
Context for code review
Context for test generation
Context for refactoring
Context for document creation
A method of managing them separately has emerged.
Just like in software engineering:
abstract
Separation of interests
Modularization
Just like that, a similar trend is emerging in AI utilization. (That's typical of engineers and developers!!)
And this flow naturally led to the concept of an Agent.
Instead of one huge prompt:
Multiple agents with separated roles
Agent specialized for specific tasks
Multi-Agent structure that collaborates with each other
I started using it.
The appearance of Agent Harness
A concept that takes this a step further has even emerged: the Agent Harness. (I have already introduced it in an Opencode blog post.)
Now, instead of a person manually running the Agents one by one:
Automatically orchestrate multiple agents and
parallel processing and
Distribute the work and
Combining results
Structures are being built.
In other words, the way AI is utilized is increasingly:
Prompt→ Skill→ Agent→ Agent HarnessIt is becoming more advanced in form.
Quality and productivity have improved tremendously.
But at the same time, a new problem arose.
Utilizing AI leads to an explosive increase in document production.
for example:
Summary of requirements
Planning document
API Specification
Things like that have started to be generated almost automatically.
The problem started here.
AI makes documents really well.
The problem is that people can't read all of it.
I connect AI to document platforms like Confluence, Notion, and Google Drive:
Document creation
Document Management
Automatic Summary
Development Automation
I've actually done a lot of the same things.
However, there was only one thing I felt.
As AI performance improves
People end up reading documents less.
The quantity and quality of the documents continue to improve,
Humans cannot verify all of that, so it ends up being summarized by AI.
The moment has arrived where "AI generation cost < human verification cost."
I started thinking about how I could solve this problem.
A document that is good for AI is different from a document that is good for humans.
These days, if you look at online communities or YouTube, they are largely divided into two factions.
I like Markdown(.md)
I like HTML
In the former case, it is because AI views it in the most efficient form for reading and understanding, and in the latter case, it is said that HTML is better because .md is difficult for humans to read, making it easier for humans to read.
I'll show you an example with a photo.
As shown in the photo, MD files make it difficult to utilize horizontal space effectively, and they appear to be more visually space-efficient. However, because they are written according to a specific format, they are likely much more AI-friendly. On the other hand, HTML offers a very flexible UI. Therefore, it looks visually clean to humans and allows for better control over information density.
Now, let's examine the arguments, pros, and cons of the .md faction and the .html faction.
Markdown(.md) document file
The Markdown camp is basically:
Let's create documents that are easy for AI to read
It is close to the philosophy that...
Actually, Markdown is a really good format for AI to read.
because:
The structure is simple and
The hierarchy is clear and
It is because the semantic structure is directly revealed in the text.
for example:
# Project structure## certification- Use JWT- Using Redis Session## Code Style- any prohibited- eslint strict modeThis structure is very easy for AI to understand.
LLM, in particular:
#
##
List
Code block
It infers importance and hierarchy through the same structure.
=> Apply weight calculation through layers (pass attention) => Lost in the Middle, Primary / Recency Bias mitigation
So, Markdown is not just a simple document, but:
AI-friendly structured text
It is close to.
And actually:
Easy Git diff management
Convenient version management
Good token efficiency
parsing stable
They have the same advantages.
HTML(.html) document
Markdown is perfectly fine when the document is small. However, it becomes a different story as the project grows in scale.
for example:
Hundreds of pages of requirements
Complex state flow
Multi-Agent Structure
Authority system
business processes
System relationship diagram
If you start expressing the same things using only Markdown, you will quickly reach your limits.
Because people:
Visual emphasis
layout
color
Interaction
Space separation
It is because it reads information through.
In other words, humans are better than simple text:
Visual Information Architecture
I read it much better.
For this reason, HTML-based document flow has also been growing recently.
The philosophy of the HTML camp is:
Let's create human-verifiable documents
It is close to.
HTML is not just about making things look pretty:
Information density control
Interaction
Visual layering
Expression of complex relationships
It is strong against.
For example:
Foldable section
Visualization of state flow
Agent Relationship Diagram
Emphasize risk factors
Task progress
Automatic summary card
Interactive documents
You can express the same things much more naturally.
Especially in the Agent Harness era:
AI generates and
Human verification and
AI executes again
Because the loop keeps repeating,
The importance of “documents that people can understand quickly” is growing tremendously.
Ultimately, what matters is "who reads it."
I think the division between the .html and .md camps will become meaningless. Ultimately, both will be used appropriately depending on who is reading the document.
If it is a document read by AI:
Structuring
Simplicity
Token efficiency
semantic hierarchy
That is important.
Conversely, if it is a document read by humans:
Visual structure
Quick Scan
stress
Information compression
Interaction
This becomes important.
In other words, I think that documents in the AI era will eventually be separated into an AI Layer and a Human Layer.
Ultimately, manage both with "Original" + "View"
I think that eventually, the structure will be separated into an AI Layer and a Human Layer, with both being managed. Furthermore, rather than the Human Layer being managed separately, I believe the direction will be to define a format where AI converts .md files into Views, and humans will build them when necessary. (A very, very personal opinion)
Just as React separated State and UI, ultimately, the source content and view will be managed from an engineering perspective.
So, if I were to represent the flow I envisioned, I think it would be as follows.

conclusion
If you look at the news these days, there are continuous instances of developers being rehired after having been laid off. I believe the reason for this is that there are limits to one person handling a wide range of tasks, and ultimately, decisions regarding what needs to be done in the real world are made through human interaction. If AI creates things without even knowing what it is trying to achieve, I think we will end up with products that are beyond our control.
The day is coming when the primary focus of AI utilization will not be code, but rather human communication and documentation that allows for rapid comprehension. As a developer, I must continue to build my capabilities to be proficient in coding, use AI effectively according to the situation, and leverage AI to overcome communication and documentation challenges. Let's do this!


