Claude Code best-practice repository walkthrough and practical guide

As Claude Code usage grows, tips on configuration and workflows are starting to pile up. I came across a repository called claude-code-best-practice on GitHub. Created in October 2025, it has since passed 1,500 stars. After reading through it, I found it quite practical, so here is a summary.

Repository overview

This is not an application codebase. It is a collection of configuration patterns and templates for Claude Code, covering topics such as:

How to write and maintain CLAUDE.md
The Command / Agent / Skills 3-layer architecture
Notification system using Hooks
Complete settings.json option reference
CLAUDE.md / Skills loading behavior in monorepos
RPI (Research, Plan, Implement) workflow

Lessons from the author’s experience

The README’s “MY EXPERIENCE” section contains insights gained from heavy real-world use. This is probably the most valuable part for developers.

Keep CLAUDE.md under 150 lines

If it gets too long, Claude starts ignoring instructions. The author notes “still not 100% guaranteed,” but shorter files clearly improve compliance.

As for /memory, /rules, and constitution.md, the author dismisses them with “does not guarantee anything.” Writing directly in CLAUDE.md is the most reliable approach.

Be deliberate about context management

Manually run /compact when context usage reaches 50%
Split subtasks so each can be completed within 50% of the context
Continuously monitor context usage via the status line

When the context overflows, Claude’s output quality drops sharply. The key insight is to manage it proactively. This is especially effective for larger implementation tasks.

Small tasks don’t need workflows

vanilla cc is better than any workflows with smaller tasks

This is an important point. Building workflows can become a goal in itself. For simple bug fixes or single-file changes, just asking Claude Code directly is faster.

Other practical tips

Always start in plan mode — don’t let it write code immediately
Commit after every completed task — avoid large monolithic commits
Set defaultMode: "bypassPermissions" in settings.json — a safer way to skip permission checks than the dangerously--skip-permissions flag
Wispr Flow (voice prompting) is claimed to deliver 10x productivity gains

Command, Agent, Skills: the 3-layer architecture

The core architectural pattern of this repository, illustrated with a weather data example.

Role of each layer

Layer	Location	Role
Command	`.claude/commands/*.md`	Entry point. User invokes it with `/command-name`
Agent	`.claude/agents/*.md`	Workflow executor. Preloads and uses Skills
Skills	`.claude/skills/*/SKILL.md`	Domain knowledge and procedures. Injected into the Agent’s context

Example: weather workflow

User runs /weather-orchestrator
The command launches the weather agent
The agent has weather-fetcher and weather-transformer skills preloaded
The agent follows the skills’ procedures to execute tasks in sequence

# .claude/agents/weather.md frontmatter
---
name: weather
description: Use this agent PROACTIVELY when you need to fetch and transform weather data
tools: WebFetch, Read, Write
model: haiku
color: green
skills:
  - weather-fetcher
  - weather-transformer
---

The key idea is Progressive Disclosure. Skill contents are preloaded when the agent starts, but the agent itself is not launched until invoked by a command. Information enters the context only when and where it is needed.

Build feature-specific agents, not generic ones

The author advises: build “feature specific subagents” rather than generic ones like “general qa” or “backend engineer.” Generic agents tend to bloat the context, diluting specialized instructions.

Voice notifications with Hooks

Claude Code can run shell scripts on various events (before/after tool use, session start/end, pre-compact, etc.). This repository builds a notification system using audio files generated with ElevenLabs TTS.

{
  "hooks": {
    "PreToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/hooks.py",
            "timeout": 5000
          }
        ]
      }
    ]
  }
}

Different sounds play for different events — a dedicated sound for git commits, for example. Configuration uses a two-tier structure: hooks-config.json (shared with team) and hooks-config.local.json (personal, gitignored).

Being able to hear when a long task finishes while browsing something else is surprisingly handy.

settings.json reference

The file reports/claude-settings.md documents every settings.json option comprehensively. It serves as a solid supplement to the official documentation.

The permission syntax reference is particularly useful:

{
  "permissions": {
    "allow": [
      "Edit(*)",
      "Bash(npm run *)",
      "Bash(git *)",
      "WebFetch(domain:*)",
      "mcp__*"
    ],
    "deny": [
      "Read(.env)",
      "Read(./secrets/**)"
    ]
  }
}

Wildcards like Bash(npm run *) let you specify command patterns. Adding .env and secrets/ to the deny list prevents accidental exposure of sensitive information.

CLAUDE.md and Skills behavior in monorepos

The repository includes a research report for those working in large-scale projects.

CLAUDE.md loading

Upward (Ancestor Loading): From the launch directory upward, all CLAUDE.md files found are loaded at startup
Downward (Descendant Loading): CLAUDE.md files in subdirectories are lazy-loaded when files in those directories are accessed

In other words, the root CLAUDE.md is always loaded, but packages/frontend/CLAUDE.md is not loaded until Claude touches a frontend file.

Skills loading

Unlike CLAUDE.md, Skills do not search upward.

Skills in the project root’s .claude/skills/ are always loaded
Skills in subdirectories are auto-detected when files in those directories are accessed
Skill descriptions are always in the context, but the body is only loaded when the skill is invoked

RPI workflow

A systematic workflow for large feature development, structured in three phases: Research, Plan, Implement.

Research phase

Run with /rpi:research. Agents such as requirement-parser, product-manager, and senior-software-engineer analyze feasibility and deliver a GO/NO-GO decision.

Plan phase

Run with /rpi:plan. Automatically generates PM requirements (pm.md), UX design (ux.md), technical design (eng.md), and an implementation roadmap (PLAN.md).

Implement phase

Run with /rpi:implement. Implements phase by phase based on PLAN.md, with a code-reviewer agent performing reviews.

Honestly, this workflow is overkill for solo projects or blog maintenance, but it is a useful reference for team development or large product features. The design of “stop if Research returns NO-GO” is a solid mechanism for preventing wasted implementation effort.

What to adopt in practice

There is no need to adopt everything. Pick what fits your project’s scale.

Solo or small projects:

Keep CLAUDE.md under 150 lines
Manual compact at 50% context usage
Permission settings in settings.json
Run small tasks directly without workflows

Medium to large projects:

Command, Agent, Skills 3-layer structure
Feature-specific agent design
Hooks-based notifications
CLAUDE.md / Skills placement strategy for monorepos

Team development:

RPI workflow
Shared settings.json and hooks-config.json
Separate personal settings via settings.local.json and hooks-config.local.json

The repository is designed to work as a reference implementation, so the most practical approach is to copy just the parts you need into your own project.