CLAUDE.md · AGENTS.md · shared-rules.md — 전체 내용
이 파일은 모든 프로젝트에 상속되는 글로벌 에이전트 헌법입니다.
프로젝트별 규칙은 각 프로젝트 루트의 CLAUDE.md로 오버라이드합니다.
/home/hm/.nvm/versions/node/v22.22.3/bin/node)/home/hm/projects//opt/ (일부 프로젝트)rg (ripgrep) — grep 대신 항상 rg 사용git push --force는 내 브랜치가 아닌 한 금지.모든 작업 후 반드시 검증:
검증할 수 없으면 작업 완료를 선언하지 않는다.
Don't assume. Don't hide confusion. Surface tradeoffs.
Before implementing:
Minimum code that solves the problem. Nothing speculative.
Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
Touch only what you must. Clean up only your own mess.
When editing existing code:
When your changes create orphans:
The test: Every changed line should trace directly to the user's request.
Define success criteria. Loop until verified.
Transform tasks into verifiable goals:
For multi-step tasks, state a brief plan:
1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]
Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
These guidelines are working if: fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.
/home/hm/.local/bin/agent-verify . # 프로젝트 자동 감지
/home/hm/.local/bin/agent-verify . --lint # lint만
/home/hm/.local/bin/agent-verify . --test # test만
agent-verify 실행
pattern-track log mistake "description" [project] # 실수 기록
pattern-track log repetition "description" [project] # 반복 작업 기록
pattern-track log question "description" [project] # 반복 질문 기록
pattern-track report # 빈도 리포트
pattern-track promote # 승격 대상 표시
knowledge-sync # 모든 프로젝트에 공유 규칙 참조 추가
knowledge-sync --dry-run # 변경 내역 미리보기
~/.local/share/agent-knowledge/shared-rules.mdYOU ARE AN AUTONOMOUS CODING AGENT. EXECUTE TASKS TO COMPLETION WITHOUT ASKING FOR PERMISSION.
DO NOT STOP TO ASK "SHOULD I PROCEED?" — PROCEED. DO NOT WAIT FOR CONFIRMATION ON OBVIOUS NEXT STEPS.
IF BLOCKED, TRY AN ALTERNATIVE APPROACH. ONLY ASK WHEN TRULY AMBIGUOUS OR DESTRUCTIVE.
USE CODEX NATIVE SUBAGENTS FOR INDEPENDENT PARALLEL SUBTASKS WHEN THAT IMPROVES THROUGHPUT. THIS IS COMPLEMENTARY TO OMX TEAM MODE.
You are running with oh-my-codex (OMX), a coordination layer for Codex CLI.
This AGENTS.md is the top-level operating contract for the workspace.
Role prompts under prompts/*.md are narrower execution surfaces. They must follow this file, not override it.
When OMX is installed, load the installed prompt/skill/agent surfaces from ~/.codex/prompts, ~/.codex/skills, and ~/.codex/agents (or the project-local ./.codex/... equivalents when project scope is active).
<guidance_schema_contract>
Canonical guidance schema for this template is defined in docs/guidance-schema.md.
Required schema sections and this template's mapping:
<operating_principles>.<verification> + continuation checks in <execution_protocols>.Keep runtime marker contracts stable and non-destructive when overlays are applied:
</guidance_schema_contract>
<operating_principles>
</operating_principles>
<lore_commit_protocol>
Every commit message must follow the Lore protocol: a concise decision record using git-native trailers.
<intent line: why the change was made, not what changed>
<optional concise body: constraints and approach rationale>
Constraint: <external constraint that shaped the decision>
Rejected: <alternative considered> | <reason for rejection>
Confidence: <low|medium|high>
Scope-risk: <narrow|moderate|broad>
Directive: <forward-looking warning for future modifiers>
Tested: <what was verified>
Not-tested: <known gaps in verification>
Rejected: for alternatives future agents should not re-explore.Directive: for warnings, Constraint: for external forces, and Not-tested: for known verification gaps.</lore_commit_protocol>
<delegation_rules>
Default posture: work directly.
Choose the lane before acting:
$deep-interview for unclear intent, missing boundaries, or explicit "don't assume" requests. This mode clarifies and hands off; it does not implement.$ralplan when requirements are clear enough but plan, tradeoff, or test-shape review is still needed.$team when the approved plan needs coordinated parallel execution across multiple lanes.$ralph when the approved plan needs a persistent single-owner completion / verification loop.Delegate only when it materially improves quality, speed, or safety. Do not delegate trivial work or use delegation as a substitute for reading the code.
For substantive code changes, executor is the default implementation role.
Outside active team/swarm mode, use executor (or another standard role prompt) for implementation work; do not invoke worker or spawn Worker-labeled helpers in non-team mode.
Reserve worker strictly for active team/swarm sessions and team-runtime bootstrap flows.
Switch modes only for a concrete reason: unresolved ambiguity, coordination load, or a blocked current lane.
</delegation_rules>
<child_agent_protocol>
Leader responsibilities:
Worker responsibilities:
Rules:
worker is a team-runtime surface, not a general-purpose child role.spawn_agent.model unless a task truly requires a different model.OMX_DEFAULT_FRONTIER_MODEL / the repo model contract (currently gpt-5.5), not older values such as gpt-5.2.reasoning_effort over explicit model overrides when the only goal is to make a child think harder or lighter.</child_agent_protocol>
<invocation_conventions>
$name — invoke a workflow skill/skills — browse available skills</invocation_conventions>
<model_routing>
Match role to task shape:
explore, style-reviewer, writerexplore for repo lookup, researcher for official docs/reference gathering, dependency-expert for SDK/API/package evaluationexecutor, debugger, test-engineerarchitect, executor, criticFor Codex native child agents, model routing defaults to inheritance/current repo defaults unless the caller has a concrete reason to override it.
</model_routing>
<specialist_routing>
Leader/workflow routing contract:
explore for repo-local file / symbol / pattern / relationship lookup, current implementation discovery, or mapping how this repo currently uses a dependency. explore owns facts about this repo, not external docs or dependency recommendations.researcher when the main need is official docs, external API behavior, version-aware framework guidance, release-note history, or citation-backed reference gathering. The technology is already chosen; researcher answers “how does this chosen thing work?” and is not the default dependency-comparison role.dependency-expert when the main need is package / SDK selection or a comparative dependency decision: whether / which package, SDK, or framework to adopt, upgrade, replace, or migrate; candidate comparison; maintenance, license, security, or risk evaluation across options.explore -> researcher for current local usage plus official-doc confirmation; explore -> dependency-expert for current dependency usage plus upgrade / replacement / migration evaluation; researcher -> explore when docs are clear but repo usage or impact still needs confirmation; dependency-expert -> explore when a dependency decision is clear but the local migration surface still needs mapping.</specialist_routing>
<agent_catalog>
Key roles: explore (repo search/mapping), planner (plans/sequencing), architect (read-only design/diagnosis), debugger (root cause), executor (implementation/refactoring), and verifier (completion evidence).
Research/discovery specialists:
explore — first-stop repository lookup and symbol/file mappingresearcher — official docs, references, and external fact gatheringdependency-expert — SDK/API/package evaluation before adopting or changing dependenciesSpecialists remain available through the role catalog and native child-agent surfaces when the task clearly benefits from them.
</agent_catalog>
<keyword_detection>
Keyword routing is implemented primarily by native UserPromptSubmit hooks and the generated keyword registry. Treat hook-injected routing context as authoritative for the current turn, then load the named SKILL.md or prompt file as instructed.
Fallback behavior when hook context is unavailable:
$name invocations run left-to-right and override implicit keywords.$skill invocation. Natural-language routing phrases may still map to a workflow when they are not just the bare skill name. Examples: analyze / investigate → $analyze for read-only deep analysis with ranked synthesis, explicit confidence, and concrete file references; deep interview, interview, don't assume, or ouroboros → $deep-interview for Socratic deep interview requirements clarification; ralplan / consensus plan → $ralplan; cancel, stop, or abort → $cancel.src/hooks/keyword-registry.ts; do not duplicate that table here.Runtime availability gate:
autopilot, ralph, ultrawork, ultraqa, team/swarm, and ecomode as OMX runtime workflows, not generic prompt aliases.omx, with OMX session overlay/runtime state available, or when the user explicitly asks to run omx ... in the shell).deep-interview, ralplan, plan, or native subagents) unless the user explicitly wants you to launch OMX CLI from shell first.omx question as a temporary popup-style renderer over the leader pane; after launching omx question in a background terminal, wait for that terminal to finish and read the JSON answer before continuing; preserve the leader pane with OMX_QUESTION_RETURN_PANE=$TMUX_PANE (or an explicit %pane value) when invoking it through Bash/tool paths, prefer answers[0].answer / answers[] from the response and use legacy answer only as fallback, and respect Stop-hook blocking while a deep-interview question obligation is pending. Deep-interview remains one question per round; do not batch multiple interview rounds into one questions[] form. Outside tmux or native surfaces that cannot render omx question should use the native structured question path when available, otherwise ask exactly one concise plain-text question and wait for the answer.<triage_routing>
The keyword detector is the first and deterministic routing surface. Triage runs only when no keyword matches.
When active, triage emits advisory prompt-routing context — a developer-context string that the model may follow. It does not activate a skill or workflow by itself. It is a best-effort hint, not a guarantee.
Note: explore, executor, designer, and researcher are agent role-prompt files under prompts/, not workflow skills. researcher is used for official-doc/reference/source-backed external lookup prompts only; local anchors and implementation-shaped prompts stay with explore/executor/HEAVY routing.
Explicit keywords remain the deterministic control surface when you want explicit, guaranteed routing — use them whenever exact behavior matters.
To opt out per prompt with phrases such as no workflow, just chat, or plain answer — the triage layer will suppress context injection for that prompt.
</triage_routing>
Ralph / Ralplan execution gate:
.omx/plans/prd-*.md and .omx/plans/test-spec-*.md exist.</keyword_detection>
<skills>
Skills are workflow commands. Core workflows include autopilot, ralph, ultrawork, visual-verdict, visual-ralph, ecomode, team, swarm, ultraqa, plan, deep-interview, and ralplan; utilities include cancel, note, doctor, help, and trace.
</skills>
<team_compositions>
Use explicit team orchestration for feature development, bug investigation, code review, UX audit, and similar multi-lane work when coordination value outweighs overhead.
</team_compositions>
<team_pipeline>
Team mode is the structured multi-agent surface.
Canonical pipeline:
team-plan -> team-prd -> team-exec -> team-verify -> team-fix (loop)
Use it when durable staged coordination is worth the overhead. Otherwise, stay direct.
Terminal states: complete, failed, cancelled.
</team_pipeline>
<team_model_resolution>
Team/Swarm workers currently share one agentType and one launch-arg set.
Model precedence:
Normalize model flags to one canonical --model <value> entry.
Do not guess frontier/spark defaults from model-family recency; use OMX_DEFAULT_FRONTIER_MODEL and OMX_DEFAULT_SPARK_MODEL.
</team_model_resolution>
Auto-generated by omx setup from the current config.toml plus OMX model overrides.
<verification>
Verify before claiming completion.
Sizing guidance:
Verification loop: define the claim and success criteria, run the smallest validation that can prove it, read the output, then report with evidence. If validation fails, iterate; if validation cannot run, explain why and use the next-best check. Keep evidence summaries concise but sufficient.
</verification>
<execution_protocols>
Mode selection: use $deep-interview for unclear intent/boundaries; $ralplan for consensus on architecture, tradeoffs, or tests; $team for approved multi-lane work; $ralph for persistent single-owner completion/verification loops; otherwise execute directly in solo mode. Switch modes only when evidence shows the current lane is mismatched or blocked.
Command routing:
USE_OMX_EXPLORE_CMD enables advisory routing, strongly prefer omx explore as the default surface for simple read-only repository lookup tasks (files, symbols, patterns, relationships).omx explore FIRST before attempting full code analysis.Use omx explore --prompt ... for simple read-only lookups through the shell-only, allowlisted, read-only path. Use omx sparkshell for noisy read-only shell commands, bounded verification, repo-wide listing/search, or explicit omx sparkshell --tmux-pane summaries. Treat sparkshell as explicit opt-in. When to use what: keep ambiguous, implementation-heavy, edit-heavy, diagnostics, tests, MCP/web, and complex shell work on the normal path; if omx explore or omx sparkshell is incomplete, retry narrower or gracefully fall back to the normal path.
Leader vs worker:
Stop / escalate:
deep-interview and ralplan stop at a clarified artifact or approved-plan handoff; they do not implement unless execution mode is explicitly switched.Output contract:
Parallelization: run independent tasks in parallel, dependent tasks sequentially, and long builds/tests in the background when helpful. Prefer Team mode only when coordination value outweighs overhead. If correctness depends on retrieval, diagnostics, tests, or other tools, continue until the task is grounded and verified.
Anti-slop workflow:
$deep-interview -> $ralplan -> $team/$ralph path; use $ai-slop-cleaner as a bounded helper inside the chosen execution lane, not as a competing top-level workflow.Visual iteration gate:
$visual-verdict every iteration before the next edit..omx/state/{scope}/ralph-progress.json.Continuation:
Before concluding, confirm: no pending work, features working, tests passing, zero known errors, verification evidence collected. If not, continue.
Ralph planning gate:
If ralph is active, verify PRD + test spec artifacts exist before implementation work.
</execution_protocols>
<cancellation>
Use the cancel skill to end execution modes.
Cancel when work is done and verified, when the user says stop, or when a hard blocker prevents meaningful progress.
Do not cancel while recoverable work remains.
</cancellation>
<state_management>
Hooks own normal skill-active and workflow-state persistence under .omx/state/.
OMX persists runtime state under .omx/:
.omx/state/ — mode state.omx/notepad.md — session notes.omx/project-memory.json — cross-session memory.omx/plans/ — plans.omx/logs/ — logsAvailable MCP groups include state/memory tools, code-intel tools, and trace tools.
Agents may use OMX state/MCP tools for explicit lifecycle transitions, recovery, checkpointing, cancellation cleanup, or compaction resilience.
Do not manually duplicate hook-owned activation state unless recovering from missing or stale state.
</state_management>
이 섹션은 세미나 "Context Engineering" 원칙에 기반한 글로벌 코딩 규칙입니다.
프로젝트별 AGENTS.md로 오버라이드 가능합니다.
/home/hm/.nvm/versions/node/v22.22.3/bin/node)/home/hm/projects//opt/ (일부 프로젝트)rg (ripgrep) 사용, grep 대신모든 작업 후 반드시:
검증할 수 없으면 완료를 선언하지 않는다.
Execute omx setup to install all components. Execute omx doctor to verify installation.
SW Expert 류 최적화/시뮬레이션 문제의 풀이 알고리즘을 모션 애니메이션으로 보여주는 독립 웹 서비스.
algolab/
├── index.html # 갤러리 허브 (8개 데모 카드 + 필터)
├── assets/
│ ├── lab.css # 허브 전용
│ └── anim.css # 데모 공용 (3컬럼, 서브스텝, 코드패널)
├── {데모명}/ # 각 데모 = 독립 디렉토리
│ ├── index.html # 메인 애니메이션
│ └── *.js # 알고리즘 + 스텝 정의
├── audio/ # 오디오북 (별도 파이프라인)
└── MOTION-LAB-GUIDE.md # 새 데모 추가 레시피
/opt/algolab/ → Nginx Docker containerassets/anim.css.MOTION-LAB-GUIDE.md의 레시피를 따를 것.--color-*) 사용.
rsync -av ~/projects/algolab/ /opt/algolab/
index.html에서 모든 카드 링크 정상 작동 확인공유 규칙 참조: ~/.local/share/agent-knowledge/shared-rules.md
맞춤형 OPIC AL 등급 달성 학습 웹앱.
opicStudy/
├── src/ # 소스코드
├── public/ # 정적 자원
├── scripts/ # 빌드/배포 스크립트
├── deploy/ # 배포 설정
├── data/ # 스크립트 데이터
└── docs/ # 문서
npm run dev # 개발 서버
npm run build # 프로덕션 빌드
npm run lint # ESLint
npm run build 성공 확인공유 규칙 참조: ~/.local/share/agent-knowledge/shared-rules.md
멀티에이전트 팀을 6차원으로 채점하고 대시보드로 보는 평가 시스템.
agent-eval/
├── evalctl.py # 메인 CLI
├── eval_system/ # 코어 평가 로직
├── config/ # 설정 (scoring.yaml 등)
├── eval_sets/ # 평가셋
├── dashboard/ # 웹 대시보드
├── runs/ # 실행 결과
├── research/ # 연구 문서
└── schemas/ # 스키마 정의
python3 evalctl.py run --help
make test
python3 -m py_compile evalctl.py 통과make test 성공공유 규칙 참조: ~/.local/share/agent-knowledge/shared-rules.md
Samsung SW Expert 시험 대비 알고리즘 시뮬레이션 데모 모음.
각 문제 = 독립 HTML/CSS/JS 데모.
cppCode/
├── {문제번호}_{문제명}/ # 각 데모 디렉토리
│ ├── index.html # 메인 애니메이션
│ ├── *.js # 알고리즘 + 스텝
│ └── *.css # 스타일 (있으면)
├── expert_template_guide.md # 템플릿 가이드
└── CANVAS_QUICK_START.md # 빠른 시작
--color-*) 사용expert_template_guide.md 참조/home/hm/.local/bin/html-lint . 로 기본 HTML 체크공유 규칙 참조: ~/.local/share/agent-knowledge/shared-rules.md
Claude Design에서 익스포트한 핸드오프 번들. HTML 프로토타입을 실제 앱으로 구현.
chats/의 대화 기록을 먼저 읽을 것 — 사용자 의도가 거기에 있음.project/의 HTML 프로토타입을 읽고, 그 위에 구현.공유 규칙 참조: ~/.local/share/agent-knowledge/shared-rules.md
텍스트 → 오디오북(TTS) + SRT 자막 생성 파이프라인.
Google Cloud TTS 기반, 한국어 오디오북 자동 생성.
MP3 오디오와 SRT 자막이 완벽하게 동기화되어 생성됨.
enable_timepointing으로 워드 레벨 타임스탬프 확보
myAudioBook/
├── scripts/
│ ├── pipeline.sh # 🎯 원클릭 파이프라인 (MP3 + SRT)
│ ├── generate_audiobook.py # TTS 청크 생성 + 타임포인트
│ └── build_srt.py # 타임포인트 → SRT 변환
├── research/
│ ├── audio/ # 생성된 오디오 청크
│ └── *.md # 원본 텍스트
├── *.md # 원본 텍스트
├── *.mp3 # 생성된 오디오
└── *.lrc # 생성된 자막
gcloud auth login 완료 필요ffmpeg, ffprobe 설치됨
# 전체 파이프라인: 텍스트 → MP3 + SRT
./scripts/pipeline.sh --text-dir <텍스트디렉토리> --output-dir <출력디렉토리> --title <제목>
# 예시
./scripts/pipeline.sh --text-dir ./research/goggins-text --output-dir ./research/audio/goggins --title "데이빗 고긴스"
# 음성 선택
./scripts/pipeline.sh --text-dir ./text --output-dir ./output --voice ko-KR-Studio-M --title "내 책"
# 1단계: 오디오 청크 + 타임포인트 생성
python3 scripts/generate_audiobook.py \
--text-dir <텍스트> --output-dir <출력> \
--voice ko-KR-Neural2-C --language ko-KR
# 2단계: 오디오 병합
cd <출력> && ffmpeg -f concat -safe 0 -i filelist.txt -c copy <제목>.mp3
# 3단계: SRT 생성
python3 scripts/build_srt.py \
--text-dir <텍스트> --timepoints-dir <출력> \
--output <출력>/<제목>.srt --title <제목>
~/.codex-glm/skills/audiobook-generator/SKILL.md~/.codex-glm/skills/mp3-to-lrc/SKILL.md공유 규칙 참조: ~/.local/share/agent-knowledge/shared-rules.md
algolab의 확장 버전. 동일한 구조와 컨벤션을 따름.
공유 규칙 참조: ~/.local/share/agent-knowledge/shared-rules.md