{"owner":"shanraisshan","repo":"claude-code-best-practice","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md"],"files":{"CLAUDE.md":"# CLAUDE.md\n\nThis file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.\n\n## Repository Overview\n\nThis is a best practices repository for Claude Code configuration, demonstrating patterns for skills, subagents, hooks, and commands. It serves as a reference implementation rather than an application codebase.\n\n## Key Components\n\n### Weather System (Example Workflow)\nA demonstration of two distinct skill patterns via the **Command → Agent → Skill** architecture:\n- `/weather-orchestrator` command (`.claude/commands/weather-orchestrator.md`): Entry point — asks user for C/F, invokes agent, then invokes SVG skill\n- `weather-agent` agent (`.claude/agents/weather-agent.md`): Fetches temperature using its preloaded `weather-fetcher` skill (agent skill pattern)\n- `weather-fetcher` skill (`.claude/skills/weather-fetcher/SKILL.md`): Preloaded into agent — instructions for fetching temperature from Open-Meteo\n- `weather-svg-creator` skill (`.claude/skills/weather-svg-creator/SKILL.md`): Skill — creates SVG weather card, writes `orchestration-workflow/weather.svg` and `orchestration-workflow/output.md`\n\nTwo skill patterns: agent skills (preloaded via `skills:` field) vs skills (invoked via `Skill` tool). See `orchestration-workflow/orchestration-workflow.md` for the complete flow diagram.\n\n### Skill Definition Structure\nSkills in `.claude/skills/<name>/SKILL.md` use YAML frontmatter:\n- `name`: Display name and `/slash-command` (defaults to directory name)\n- `description`: When to invoke (recommended for auto-discovery)\n- `argument-hint`: Autocomplete hint (e.g., `[issue-number]`)\n- `disable-model-invocation`: Set `true` to prevent automatic invocation\n- `user-invocable`: Set `false` to hide from `/` menu (background knowledge only)\n- `allowed-tools`: Tools allowed without permission prompts when skill is active\n- `model`: Model to use when skill is active\n- `context`: Set to `fork` to run in isolated subagent context\n- `agent`: Subagent type for `context: fork` (default: `general-purpose`)\n- `hooks`: Lifecycle hooks scoped to this skill\n\n### Presentation System\nSee `.claude/rules/presentation.md` — presentation work is delegated per-presentation to `presentation-vibe-coding` (for `presentation/vibe-coding-to-agentic-engineering/`) or `presentation-claude-gemini` (for `presentation/2026-04-25-gdg-kolachi-cli-claude-code-gemini/`).\n\n### Hooks System\nCross-platform sound notification system in `.claude/hooks/`:\n- `scripts/hooks.py`: Main handler for Claude Code hook events\n- `config/hooks-config.json`: Shared team configuration\n- `config/hooks-config.local.json`: Personal overrides (git-ignored)\n- `sounds/`: Audio files organized by hook event (generated via ElevenLabs TTS)\n\nHook events configured in `.claude/settings.json`: PreToolUse, PostToolUse, UserPromptSubmit, Notification, Stop, SubagentStart, SubagentStop, PreCompact, SessionStart, SessionEnd, Setup, PermissionRequest, TeammateIdle, TaskCompleted, ConfigChange.\n\nSpecial handling: git commits trigger `pretooluse-git-committing` sound.\n\n## Critical Patterns\n\n### Subagent Orchestration\nSubagents **cannot** invoke other subagents via bash commands. Use the Agent tool (renamed from Task in v2.1.63; `Task(...)` still works as an alias):\n```\nAgent(subagent_type=\"agent-name\", description=\"...\", prompt=\"...\", model=\"haiku\")\n```\n\nBe explicit about tool usage in subagent definitions. Avoid vague terms like \"launch\" that could be misinterpreted as bash commands.\n\n### Subagent Definition Structure\nSubagents in `.claude/agents/*.md` use YAML frontmatter:\n- `name`: Subagent identifier\n- `description`: When to invoke (use \"PROACTIVELY\" for auto-invocation)\n- `tools`: Comma-separated allowlist of tools (inherits all if omitted). Supports `Agent(agent_type)` syntax\n- `disallowedTools`: Tools to deny, removed from inherited or specified list\n- `model`: Model alias: `haiku`, `sonnet`, `opus`, or `inherit` (default: `inherit`)\n- `permissionMode`: Permission mode (e.g., `\"acceptEdits\"`, `\"plan\"`, `\"bypassPermissions\"`)\n- `maxTurns`: Maximum agentic turns before the subagent stops\n- `skills`: List of skill names to preload into agent context\n- `mcpServers`: MCP servers for this subagent (server names or inline configs)\n- `hooks`: Lifecycle hooks scoped to this subagent (all hook events are supported; `PreToolUse`, `PostToolUse`, and `Stop` are the most common)\n- `memory`: Persistent memory scope — `user`, `project`, or `local` (see `reports/claude-agent-memory.md`)\n- `background`: Set to `true` to always run as a background task\n- `effort`: Effort level override: `low`, `medium`, `high`, `max` (default: inherits from session)\n- `isolation`: Set to `\"worktree\"` to run in a temporary git worktree\n- `color`: CLI output color for visual distinction\n\n### Configuration Hierarchy\n1. **Managed** (`managed-settings.json` / MDM plist / Registry): Organization-enforced, cannot be overridden\n2. Command line arguments: Single-session overrides\n3. `.claude/settings.local.json`: Personal project settings (git-ignored)\n4. `.claude/settings.json`: Team-shared settings\n5. `~/.claude/settings.json`: Global personal defaults\n6. `hooks-config.local.json` overrides `hooks-config.json`\n\n### Disable Hooks\nSet `\"disableAllHooks\": true` in `.claude/settings.local.json`, or disable individual hooks in `hooks-config.json`.\n\n## Answering Best Practice Questions\n\nWhen the user asks a Claude Code best practice question, **always search this repo first** (`best-practice/`, `reports/`, `tips/`, `implementation/`, and `README.md`) before relying on training knowledge or external sources. This repo is the authoritative source — only fall back to external docs or web search if the answer is not found here.\n\n## Workflow Best Practices\n\nFrom experience with this repository:\n\n- Keep CLAUDE.md under 200 lines per file for reliable adherence\n- `.claude/rules/*.md` with `paths:` YAML frontmatter are lazy-loaded only when Claude touches matching files; without frontmatter they load into every session like CLAUDE.md\n- Use commands for workflows instead of standalone agents\n- Create feature-specific subagents with skills (progressive disclosure) rather than general-purpose agents\n- Perform manual `/compact` at ~50% context usage\n- Start with plan mode for complex tasks\n- Use human-gated task list workflow for multi-step tasks\n- Break subtasks small enough to complete in under 50% context\n\n### Debugging Tips\n\n- Use `/doctor` for diagnostics\n- Run long-running terminal commands as background tasks for better log visibility\n- Use browser automation MCPs (Claude in Chrome, Playwright, Chrome DevTools) for Claude to inspect console logs\n- Provide screenshots when reporting visual issues\n\n## Git Commit Rules\n\nWhen committing changes, **create separate commits per file**. Do NOT bundle multiple file changes into a single commit. Each file gets its own commit with a descriptive message specific to that file's changes.\n\nFor example, if `README.md`, `best-practice/claude-subagents.md`, and a skill file all changed:\n- Commit 1: `git add README.md` → commit with README-specific message\n- Commit 2: `git add best-practice/claude-subagents.md` → commit with subagents-doc-specific message\n- Commit 3: `git add .claude/skills/weather-fetcher/SKILL.md` → commit with skill-specific message\n\nThis makes the git history cleaner and easier to review, revert, or cherry-pick individual changes.\n\n## Documentation\n\nSee `.claude/rules/markdown-docs.md` for documentation standards. Key docs:\n- `best-practice/claude-subagents.md`: Subagent frontmatter, hooks, and repository agents\n- `best-practice/claude-commands.md`: Slash command patterns and built-in command reference\n- `orchestration-workflow/orchestration-workflow.md`: Weather system flow diagram\n"}}