Ywc Ubiquitous Language

Ubiquitous Language

Announce at start: "I'm using the ywc-ubiquitous-language skill to create or update the project's shared domain vocabulary."

This skill produces or maintains docs/ubiquitous-language.md — a shared vocabulary file that aligns developers, domain experts, and LLMs on canonical term usage. It operates in three modes: new (interview-driven creation from scratch), extract (term discovery from an existing codebase), and update (incremental revision of an existing document).

Rationalization Defense

When tempted to bypass a rule, check this table first:

| Excuse | Reality | |---|---| | "Everyone on the team knows the terms — no need for a document" | LLMs do not share team knowledge. Every term the LLM misinterprets costs a correction cycle. The document is primarily for LLM context injection, not just team alignment. | | "I'll auto-extract and write the file without user confirmation" | Extracted terms without definition review produce a synonym-polluted glossary. A raw class name is not a domain term until a human confirms its meaning. Always present candidates before writing. | | "Korean translation is obvious — I'll infer it" | Machine-inferred Korean business terms introduce errors that survive in code and prompts for years. Surface every Korean equivalent to the user for confirmation. | | "Bounded Contexts add complexity for a small project, use a flat list" | A flat glossary lets homonyms (same term, different meaning in different contexts) silently coexist. Start with "Core Domain" if only one context exists — it takes one line. | | "The file already exists, I'll append without reading it" | Appending without reading creates duplicate entries and contradictory definitions. Always read the full file before any write. | | "ywc-project-docs handles the docs/ structure, I'll skip update" | ywc-project-docs manages directory skeleton and README-level docs. ywc-ubiquitous-language owns domain vocabulary content. Both must run independently. | | "DDD types (Entity, Aggregate etc.) are overkill here, skip the column" | DDD Type column is optional — controlled by --ddd flag. But the Synonyms to Avoid column is always required; it is the highest-value anti-confusion signal. |

Violating the letter of these rules is violating the spirit. A glossary with unconfirmed terms or missing synonyms degrades LLM output quality with every prompt that references it.

Arguments

| Parameter | Format | Default | Description | |-----------|--------|---------|-------------| | --mode | --mode new\|extract\|update | auto-detect | Force a specific mode (see Mode Detection below) | | --context | --context | all contexts | Scope to a single Bounded Context for extract/update | | --output | --output | docs/ubiquitous-language.md | Output file path | | --ddd | flag | off | Add DDD Type column (Entity / Value Object / Aggregate / Domain Event / Policy) | | --dry-run | flag | off | Show proposed changes without writing to disk |

Mode Detection (when --mode is omitted)

| Condition | Auto-selected mode | |---|---| | docs/ubiquitous-language.md exists | update | | File absent AND source files found (src/, app/, lib/, internal/) | extract | | File absent AND no source files | new |

Workflow

Mode: new — Interview-Driven Creation

Step 1: Domain Overview Ask the user for a 2-3 sentence description of the domain if not already in context. Identify the primary domain and any obvious sub-domains.

Step 2: Bounded Context Identification Propose "Core Domain" as the default single context. If the domain description suggests multiple areas of responsibility, propose 2-4 candidate context names and ask the user to confirm or revise. Start with the minimum set — contexts can be added in update mode.

Step 3: Term Elicitation per Context For each context, gather 5–15 core terms via conversation. For each term, collect:

• Canonical English name (the term used in code)
• Korean equivalent (always confirm with user, never infer)
• Definition: 1–2 sentences, from the domain's perspective
• Synonyms to Avoid: names that mean the same thing but must NOT be used

If --ddd flag is set, also collect: DDD Type (Entity / Value Object / Aggregate / Domain Event / Policy).

Step 4: Write File Write to --output path using the format in [references/document-format.md](references/document-format.md).

Step 5: CLAUDE.md Integration Prompt After writing, print:

★ To give LLMs automatic access to this vocabulary, add the following line to your CLAUDE.md:
  @docs/ubiquitous-language.md

---

Mode: extract — Codebase Discovery

Step 1: Scan for Candidate Terms Apply the extraction heuristics in [references/extraction-guide.md](references/extraction-guide.md). Focus on:

• Domain model class/struct names
• Repository, Service, UseCase, Handler names (strip suffix)
• Meaningful enum values
• Prominent variable names in domain logic files

Step 2: Cluster into Context Candidates Group candidates by module/package path. Propose each group as a Bounded Context name. Show the user a table:

Context candidate: "Order" (from src/order/, 12 candidates)
Context candidate: "Payment" (from src/payment/, 7 candidates)

Step 3: User Confirmation Present the full candidate list. User confirms, rejects, or relabels each term. Do not write any term the user has not confirmed.

Step 4: Definition Gathering For confirmed terms, gather definitions the same way as Mode: new — Step 3.

Step 5: Write File Same as Mode: new — Step 4 and Step 5.

---

Mode: update — Incremental Revision

Step 1: Read Existing File Read the full docs/ubiquitous-language.md. Parse all existing terms, contexts, and synonyms.

Step 2: Identify Changes Ask the user: "What changed since the last update?" Options:

• User describes new features/terms → proceed with description
• User says "check recent commits" → run git log --oneline -20 and surface domain-relevant changes
• User says "just review" → compare existing terms against current codebase naming

Step 3: Build CHANGESET Propose three lists for user confirmation:

• ADD: New terms not yet in the document
• MODIFY: Existing terms whose definition or synonyms need revision
• DEPRECATE: Terms that no longer exist in the codebase (mark with ~~strikethrough~~ + note, do not delete)

Step 4: Apply and Update Apply confirmed changes. Update the `` header. Append a brief change summary at the bottom of the file.

---

Output Format

The full format specification is in [references/document-format.md](references/document-format.md).

Summary:

# Ubiquitous Language — [Project Name]

## Overview
[Domain description, 2-3 sentences]

## Bounded Contexts
| Context | Responsibility |
|---------|---------------|

---

## [Context Name]
| Term | Korean | Definition | Synonyms to Avoid |
|------|--------|-----------|------------------|

With --ddd flag, a Type column (Entity/Value Object/Aggregate/Domain Event/Policy) is inserted between Korean and Definition.

Validation

Before declaring complete:

• [ ] Every term has a non-empty Korean equivalent (confirmed with user, not inferred)
• [ ] Every term has at least one entry in Synonyms to Avoid (or explicit — if truly none)
• [ ] No two terms share the same Korean equivalent within the same context
• [ ] docs/ubiquitous-language.md is parseable Markdown with no broken table rows
• [ ] `` header reflects today's date
• [ ] CLAUDE.md integration prompt was printed to the user

Common Mistakes

• Writing before confirming all terms — The LLM may batch terms and write immediately. Always present the full term list for one confirmation round before writing.
• Inferred Korean translations — Korean business terms that look obvious (e.g., "Order" → "주문") may still need confirmation because the team might use a specific nuance (e.g., "발주" vs "주문" for B2B vs B2C).
• Silent deprecation — Removing a term without a ~~deprecated~~ marker destroys the history of why a term was abandoned. Teams need that context.
• Flat list for multi-context domains — Without Bounded Context separation, "Account" can mean a financial account in one context and a user account in another — both valid, both conflicting.

Integration

• Upstream: ywc-plan (call during planning to establish vocabulary before spec writing), ywc-project-docs (project docs skeleton)
• Downstream: ywc-task-generator (tasks reference canonical terms), ywc-code-gen (code generation uses canonical naming), ywc-spec-validate (spec consistency check)
• Pairs with: ywc-spec-validate — spec terms should match ubiquitous language; flag mismatches

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: yongwoon
• Source: yongwoon/ywc-agent-toolkit
• License: MIT

Install and usage instructions live in the source repository linked above.