---
id: claude-md-guide
app: wkappbot-workflow
description: Newbie orientation and mandatory rules guide. Explains two-layer CLAUDE.md system global vs project repo root. Lists key mandatory rules English only code Korean haeyo-che responses speak not slack no process kill CDP port discipline delegate first terse. Self-healing CLAUDE.md patterns. How to create project CLAUDE.md from scratch when none exists. Must read on first session.
tags: [claude-md, global, project, self-healing, gg, workflow, guide, two-layer, mandatory, rules, english, korean, speak, delegate, orientation, onboarding, help, must, read, setup, language, rule, fresh, lost, confused, unsure, what, do, next, heal, fix, repair, update, stale, doctor, maintain, optimize, situation, trigger, 전역, 프로젝트, 규칙, 영어, 한국어, 안내, 필독, 뉴비, 처음, 셀프힐링, 읽어, 읽어야, 봐야, 중요, 강제, 금지, 먼저, 가이드, 어떡해, 뭐해, 몰라, 온보딩, 엠디, 클로드, 법칙, 규정, 지침, 설명, 무엇, 궁금, 헬프, 도움, 기본, 처음이야, 입문, 초급, 초보, 힐링, 고치기, 수정, 낡음, 오래됨, 최적화, 상황별, 닥터]
---

> **Refresh**: `wkappbot skill read claude-md-guide --if-newer` — v1.25 (2026-05-08)

# CLAUDE.md Role Guide: Global vs Project + Self-Healing

## Steps

1. TWO-LAYER SYSTEM: (1) Global CLAUDE.md at ~/.claude/CLAUDE.md -- applies to ALL projects, loaded first. (2) Project CLAUDE.md at repo root -- project-specific, loaded second and WINS over global on conflict.
2. GLOBAL CLAUDE.MD PURPOSE: tool-level universal rules that apply everywhere -- language, notifications, CDP port, process kill protection, delegation policy, suggest protocol, loop rules, secrets file. Do NOT put project-specific content here.
3. KEY MANDATORY RULES (memorize -- apply every session): (A) LANGUAGE: user-facing final responses = Korean polite -yo form. NEVER informal speech. Everything else = English only (code, comments, CLAUDE.md, skills, commits, docs, prompts). Non-English in code burns 2-3x tokens per session load. (B) NOTIFICATIONS: always 'wkappbot speak text --bg'. NEVER 'wkappbot slack send' -- fails silently when Slack is closed. (C) PROCESS KILL: never kill wkappbot-core.exe/wkchat.exe/wkappbot.exe directly -- route through 'wkappbot taskkill' which requires user confirmation. (D) CDP PORT: run 'wkappbot cdp open url' first, get assigned cdp:{port}, include it in every subsequent grap. Never hardcode or snoop another project port. (E) DELEGATE: default = spawn agents. Haiku for reads/surveys, codex-mini for code edits, Opus for architecture/judgment, triad for hard unknowns. Stay in orchestrator seat. (F) TERSE: responses under 80 words unless task needs detail. No preamble, no recap of what user said.
4. PROJECT CLAUDE.MD PURPOSE: domain knowledge for this repo only -- build commands, architecture overview, known gotchas, CWD shorthand, key file paths, gg Main Workflow section.
5. GG MAIN WORKFLOW SECTION (required in every project CLAUDE.md): FIRST STEP (mandatory): wkappbot skill read on-load -- handles session start, handoff context recovery, suggest triage. Always first regardless of project. LAST STEP (mandatory): wkappbot skill read repo-health-doctor -- [LITE] steps only: AGENTS.md parity, skill source_refs, gg command grounding, README sync, cross-model format check. Keeps CLAUDE.md and repo healthy after every session. Project-specific tasks go in between. Pattern: 1. wkappbot skill read on-load / 2..N-1. [project tasks] / N. wkappbot skill read repo-health-doctor
6. SITUATION-BASED SELF-HEALING -- act immediately, no confirmation needed. Find this skill: wkappbot skill search "md heal". (A) NEW REPO / no CLAUDE.md -> create from template in step 9. (B) A command just failed -> delete or fix that line immediately, commit with the code change it describes. (C) New gotcha discovered -> append one line under Gotchas section, commit same session. (D) New recurring pattern established -> add to gg Main Workflow steps. (E) File exceeds ~100 lines -> trim stale content first; if still long, extract patterns into MEMORIES.md -- keep CLAUDE.md under 100 lines. Then: wkappbot skill read claude-token-optimization. (F) Same subject drifts between CLAUDE.md and README.md -> fix both in one commit. (G) Session ending after significant work -> scan for stale content, then: wkappbot skill read handoff-checklist. To review which session you are in: wkappbot session list --claude --cwd. (H) Before release or repo feels stale -> close Daily issues, check unanswered comments, fill empty CLAUDE.md sections: wkappbot skill read repo-health-doctor.
7. HOW TO EDIT: project CLAUDE.md -> Edit tool directly (it is a project file, not a skill). Global CLAUDE.md -> Edit tool at ~/.claude/CLAUDE.md. After any edit: verify the gg section still runs top-to-bottom without errors. Never add Korean text to CLAUDE.md -- English only, Korean burns 2-3x tokens on every load.
8. SHARED MARKDOWN RULE: if the same subject appears in README.md and CLAUDE.md, they must agree. Update both in the same commit. Drift = wasted tokens on every future session.
9. NO PROJECT CLAUDE.MD YET? Create it: (1) Write the file with the template below. (2) Fill project name, build command, architecture 1-3 sentences. (3) Add gg Main Workflow with on-load first and repo-health-doctor last. (4) git add CLAUDE.md and commit. MINIMUM TEMPLATE: # ProjectName -- AI Session Guide. Build: build-command. Architecture: 1-3 sentences. gg Main Workflow: 1. wkappbot skill read on-load 2. wkappbot suggest list 3. Agent(model:opus, prompt:triage INSERT-LIST) 4. wkappbot skill read repo-health-doctor Gotchas: add as you discover them.
