A Common Language for Talking to AI: The Secrets of 'Information Structuring' with Markdown and YAML

Hello, this is Akari.

It has been a while since my last post, but I have managed to write up to the third installment safely. The series is planned for a total of five parts.

In the previous article, 'Breaking Away from the "All-in-One Prompt"', I introduced the technique of separating prompt 'instructions' from contextual 'background knowledge', and offloading heavy settings or rules into external files (cheat sheets).

However, many people hit a wall here.
"I fed the AI my setting documents and meeting minutes, but it didn't work as intended at all..."
Have you ever had that experience?

Actually, just handing over information is not enough. This time, I will explain the most important task in context engineering: 'How to provide information in a way that is easy for AI to understand (structuring)'.

The Limits of 'Just Throwing It In'

For example, suppose you throw meeting minutes or internal Word specification documents directly at an AI.
While a human can judge from the context that 'this is important' or 'this is a supplement', to an AI, it is nothing more than a 'string of characters'.

Natural language (the sentences we speak and write every day) is extremely ambiguous.
If subjects are omitted or emotional expressions are mixed in, the AI cannot correctly pick up 'where the constraints for the AI are' and 'where the mere background knowledge is', resulting in misguided output.

'Easy-to-read text' for humans and 'easy-to-process data structures' for AI are completely different things.

Why does AI prefer 'structured data'?

So, what is data that is easy for AI to process?
That is 'structured data'.

Structuring, simply put, is 'clearly defining the relationships between pieces of information'.
Instead of plain text, it is the idea of giving information labels or hierarchies, such as 'this block is a rule' or 'this is an attribute called character name'.

Since AI internally calculates and processes words probabilistically, the clearer these 'information hierarchies' and 'attribute definitions' are, the less likely it is to hallucinate (lie), and the more stably it can provide high-precision answers.

As for concrete practical methods, I will introduce two powerful weapons: 'Markdown' and 'YAML'.

Practice 1: Hierarchization with Markdown

The easiest and most immediately usable method is Markdown notation.
(By the way, the article you are reading right now is also written in a Markdown structure.)

Use '#' for headings and '-' for lists. Even just doing this makes the structure of the information dramatically easier for the AI to understand.

[Example of plain text (AI gets confused)]

[Example structured with Markdown (Easy for AI to understand)]

# 記事の要件定義

## テーマ
- AIエンジニアリングについて

## ターゲット読者
- 若手エンジニア

## 制約条件
- 文字数：1000文字程度
- トーン＆マナー：専門用語は使わず、わかりやすく

By simply separating 'what is the theme' and 'what are the constraints' using blocks (headings) like this, the number of things the AI overlooks will decrease dramatically.

Practice 2: Thorough use of key-value pairs with YAML

When you want to control an AI as a system even more strictly than with Markdown, the 'YAML' notation is very useful.
YAML is a data format that describes 'attributes (keys)' and 'values' as pairs.

It is especially powerful when you want the AI to recognize detailed parameters without wavering, such as character settings for a novel or defining a consistent worldview.

【Example of character settings in YAML】

Character:
  Name: "アカリ"
  Age: 25
  Role: "AIエンジニア"
  Personality:
    - 温厚
    - ロジカル
    - 面倒見が良い
  ToneOfVoice: "です・ます調（柔らかい口調）"

By writing it this way, the AI processes the information completely as a database, understanding that 'the Name attribute contains Akari' and 'the Personality list has three elements.'
Since all ambiguity of natural language is eliminated, the reproducibility when you instruct the AI to 'answer according to Akari's ToneOfVoice' in your prompt will skyrocket.

Conclusion: Mastering a common language with AI

The essence of context engineering is not just passing external information.
It is about 'translating and passing it in a protocol (common language) that an alien intelligence like AI can interpret most accurately.'

Markdown hierarchies and YAML key-values.
By mastering these two secrets of 'structuring,' the power of the cheat sheet (context) you provide will increase tenfold or even a hundredfold.

But did you think, 'It seems like a hassle to write such clean Markdown or YAML by myself every time...'?
Rest assured. Actually, you don't even need to write this structured context by hand from scratch.

💡 Akari's perspective: Have the AI itself structure it into a 'format that is easy for it to read'

Try throwing your thoughts at the AI in natural language and asking it to 'structure this in Markdown.' The AI will neatly organize your words into the 'format that it finds easiest to process.'

And here is the important part. If you look at the results structured by the AI and feel, 'Huh? This is a bit off from my intention.'
That means,'the gap in understanding with the AI that had already occurred at the point of the natural language you first provided'has been clearly visualized through structuring.

In the next installment of 'Specifications Not Written from Scratch,' I will introduce practical tips for automatically forging the ultimate context through 'wall-bouncing' with AI by utilizing this property. Stay tuned!