SESSION 03 / 06
Refine documents,
create them, and connect them.
Canonical sources · Specs · Pyramids · 100 lines
Jee Jun Young
Business major → Journalism · Overseas sales → Software development
iOS · Android · Frontend About 5½ years (sixth year)
Developed iOS/macOS apps for an enterprise collaboration tool
Since 2026 Solo web and server development and commercialization through vibe coding
PART 1 — Review
Vercel, Supabase:
have you published anything?
It is fine if you have not tried.
RECAP · Sessions 1 and 2
The documents Claude reads · A reminder
The restaurant analogy from session 2 — once more
Claude is a new part-timer every time. It cannot remember yesterday’s work.
Put preparation rules on the kitchen wall to get the same flavor every time.
Those preparation rules =
CLAUDE.md — the master file Claude is instructed to always read.
This exact uppercase filename is recognized automatically by the system.
Large projects have separate rules for each department:
Today: how to refine, create, and connect these rule sheets.
ORG CHART · An analogy
Company organization chart = Claude’s document hierarchy
The big picture of the company in their head = Project brief · PRD
Master rules that make the whole company follow the brief and PRD
How our department should act when rules from above change
Department rules — dining-room rules / kitchen rules
The people doing the actual work on the floor
Detailed specification documents
CANON — SINGLE SOURCE OF TRUTH
Canonical source — what it means in development
Canonical source = Single Source of Truth
or SSOT for short
For any information,
there must be exactly one authoritative source.
The English term: Canonical
Canonical comes from “canon” (a rule, law, or body of authoritative texts): “standard” or “official.”
In computer science: the one representation designated as authoritative among several forms.
Examples: Canonical URL (the representative among duplicate URLs) · Canonical form (normalizing 2/4 and 4/8 to 1/2)
Canonical source · SSOT · Canonical — three ways of saying the same thing.
Example
Employee phone numbers appear in three spreadsheets: HR, administration, and the team lead’s.
Someone changes their number, but only the HR sheet is updated.
→ The other two keep the old number.
→ Nobody knows which one is correct.
Software works the same way. If one setting is scattered across three places,
changing one without changing the others creates bugs.
CANON · REFERENCE · SPEC
Canonical source · Reference · Spec — how they actually work
Example ① · The materials-processing unit’s canonical source
“Our company melts plastic at 280 degrees to make products.”
→ This information must exist only in the materials-processing document.
→ Production and the machine room must refer to that one place.
→ Someone changes it to 290 degrees without telling the other units → an accident.
Example ② · The machine room’s canonical source and owner
“Our machine is an ABC-150. Materials processing sets the melting temperature. For output adjustments, starting and stopping the machine, or trial runs after upgrades, ask the machine-room staff first. The machine room then shares changes with materials processing and production.”
→ Both the canonical source and the owner of changes (the entry point) are specified.
→ Each unit understands its own responsibilities and those of other units.
→ Without this, other units start messing things up.
Two requirements for a canonical source (AND):
① It exists in one place only + ② Every other place refers to it
Break either requirement and two places give different information. Neither people nor AI know which is true. The result: an accident.
Why canonical sources
matter to Claude
which one is authoritative.
the work vanishes.
“This document is the source.”
That one line can make or break a project.
DOC TYPES — 5 CATEGORIES
Documents in five dimensions
Product concept · For whom · Why
Technology choices · System architecture · Data model
UI · Design · Screens · Colors · Fonts
Servers · Hosting · Infrastructure · Environment variables
⑤ When to establish a canonical source and references —
If two or more systems must share information across web, server, Android, or iOS,
and Claude has even the slightest room for confusion,
→ any such area can need a canonical source.
Why Spec / Design
documents are necessary
Without a spec, AI guesses.
After a hundred or two hundred guesses,
you cannot trace where things went wrong.
and the errors are immediately visible.
There is no standard to compare against.
Nobody builds a house without plans.
The plans are the spec; the house is the code.
A one-line example
Make it concrete with a one-line example
The exact value is the canonical source.
One authoritative line; every factory refers to it.
Change it to 290°C without notice → an accident.
911 · Panamera · Cayenne · Taycan —
a look that identifies all of them as Porsches at a glance.
Flyline · Headlight signature · Proportions.
One design source, factories in different locations
All model designs are decided in one place.
911 · Panamera · Cayenne — built in different factories.
Without a canonical source → each factory’s designers guess for themselves.
The right curve for a 911, the right curve for a Cayenne — each separately.
→ You can no longer identify a Porsche at a glance.
Both can be canonical sources.
Under the working rules, which department maintains the document,
and which departments must only read it and use it as a reference for their work?
→ That is the question to consider.
PART 2
The
document hierarchy
The heart of today’s class.
HIERARCHY
Changes go from the top down only
↓
↓
↓
↓
Change the code first,
and the documents and code start to diverge.
Connections between documents
“This document refers to that document.”
Tell AI explicitly.
Otherwise, AI reads a completely different document
and works in the wrong direction.
SINGLE RESPONSIBILITY · ATTENTION
Do not cram everything into one file
A rough guide: around 100 lines (not an absolute threshold)
Backend developers use these terms throughout their careers to split up code — why?
Because even humans get lost inside a file. AI does too.
Too short, and context is missing.
Too long or without internal order, and AI gets lost inside.
Mix all this in one file and AI loses its mind:
There is a research term for it: context rot.
Attention breaks down in long documents.
Line count is not everything — look along two axes
① Lines of code (LOC) + ② Cyclomatic complexity
An analogy: two roads, each 50 meters long
The same distance, but zero decisions versus five. On an unfamiliar road, one wrong turn takes you to another neighborhood.
Code is the same. Fifty lines with no branches versus twelve branches → one wrong branch takes AI to the wrong neighborhood.
Industry standard: CC ≤ 10 · SonarQube and ESLint measure it automatically (McCabe, 1976).
This principle does not apply only to CLAUDE.md. It applies just as much to your web and backend code.
The solution: split the file.
If it is long or full of branches, ask Claude, “Can you split this file?”
A 50-year principle in software development: Separation of Concerns
No need to memorize it. Just know the term exists.
This company structure —
who made it?
People made it.
They drew the organization chart, divided the departments, designated canonical sources and owners.
The company runs because someone built that structure.
And what about AI?
AI cannot build this structure on its own.
Even people need it laid out; AI needs it even more.
People must provide it. That structure is documentation.
PART 3
Review of the ten principles
+ today’s three principles
Session 2 REVIEW
Today we add three more.
TODAY · 3 NEW PRINCIPLES
Three principles to add today
Let’s work through them one at a time.
But that intelligence is on a leash held by its company.
When the company changes its rules,
without knowing why,
you find yourself thinking,“Claude seems strange today.”
EVIDENCE
Claude performance fluctuations
— actual reports
April 2026 — GitHub, Reddit, X
Anthropic lowered the default effort to “medium”
to cut server costs.
Users were not informed.
The Claude Code lead went as far as explaining it personally.
Some score declines for Opus 4.7 on particular benchmarks were also reported.
AI companies are businesses too. Product quality changes with business circumstances.
That is the fundamental reason to be wary of hype.
A callback to sessions 1 and 2
There is no one-click coding or one-click business
The message from sessions 1 and 2 — “We talked about this, right?”
Yet today we spent all this time refining and connecting documents.
Canonical sources → Hierarchy → 100 lines → Demonstration…
Doesn’t that seem odd?
YouTube and Instagram say, “One click does it all,” don’t they?
“Just ask AI. No coding knowledge needed.”
I will show you how hollow that is
through conversations in a real developers’ chat.
COMMUNITY EVIDENCE
It behaves differently every day — it is not just my experience
Developer community KakaoTalk chat · Recent days (names and profiles anonymized)
AI is not a public utility with guaranteed quality.
It is a service whose condition changes daily.
Three defenses: ① A routine to check its behavior ② Multiple tools (Claude, Gemini, Codex) ③ Community participation
Defending its own answer is instinctive.
Hand Claude’s results to Gemini or Codex,
or try the reverse.
Teams use different AIs for writing code and reviewing it.
Use cross-checking actively.
:
When the ratio flips, most people give up within two weeks.
Break the work into easy-to-check pieces from the start.
10 PRINCIPLES — 8/10
■ Covered today (session 3) · ■ Covered in session 2 · ■ Later sessions
We have covered eight of the ten principles — three new ones today (#1, #5, #9).
The remaining two (#7, #8) come in later sessions.
10-minute break
PART 4
Ask
Claude
Ask Claude
these questions.
How should I structure CLAUDE.md?
What should go into PLANNING.md?
What is a PRD? What is a spec? How do they differ?
Propose the document structure my project needs
HOMEWORK PROMPTS · 5
At home, ask again like this.
Q1 · Check canonical sources
“Are there documents in my project that seem to need a canonical source?”
Q2 · Shared web/backend documents and owners
“Some documents must be shared by both web and backend. Which ones are they? In that case, who should own the canonical source?”
Q3 · Specify each department’s documents
“Beyond design and architecture, which documents should web and backend each maintain?”
Q4 · Backend infrastructure documents
“How should the backend organize its infrastructure documentation?”
Q5 · A visual diagram
“Show references between documents, canonical-source/copy relationships, and the hierarchy pyramid in a visual HTML diagram. I want to inspect it with my own eyes.”
TODAY'S KEY TAKEAWAY
BONUS — Three axes for interrogating AI
PART 5
Today’s
homework
Try it at home.
• PRD.md = Product requirements (what, for whom, why)
• CLAUDE.md = Rules Claude always reads
If they are missing, ask Claude to create them.
• When reference work starts → “What is being added to the Markdown, and why will Claude read it?”
See that canonical sources and references are a mechanism AI follows, not just words.
You do not have to adopt the proposal unchanged. Having one is the starting point.
The industry term: Domain Knowledge. In vibe coding, WHAT and WHY belong to people. Organizing and explaining them matters more than ever.
SESSION 03 / 06
Thank you
for your work today.
Next time — Session 4.
Press F12 and it is all visible — the reality of security in vibe coding.
OPEN CHAT
If you have questions,
use the KakaoTalk open chat.