One Open Source Project a Day (No. 70): claude-code-best-practice - Moving from Vibe Coding to AI-Native Development

A practitioner's manual for Claude Code curated by shanraisshan. It's more than a collection of tips; it's a systematic methodology for "Agentic Engineering."

·4 min read·Tool Recommendation
Open SourceClaude CodeAIBest PracticesWorkflowAgentic Engineering

Introduction

"AI programming is not just about changing tools; it's about refactoring your development paradigm."

This is the 70th article in the "One Open Source Project a Day" series. Today, we explore claude-code-best-practice.

If you've started using Anthropic's CLI tool, Claude Code, you might have noticed a pattern: sometimes it's breathtakingly precise, other times it gets stuck in "stupid loops." This discrepancy often isn't about the model itself but how you collaborate with it. shanraisshan/claude-code-best-practice is currently the most hardcore, systematic guide for Claude Code in the community. It distills the transition from "Vibe Coding" to professional "Agentic Engineering."

What You Will Learn

  • Core mechanisms: CLAUDE.md, Skills, Hooks, and Commands.
  • Instruction Management: Writing high-quality directives that AI won't ignore.
  • Orchestrating complex cross-file and multi-step tasks.
  • Parallel agent development using Git Worktrees.
  • Practical tricks: Manual /compact, phase-gated planning, and anti-degradation strategies.

Prerequisites

  • Familiarity with the Claude Code CLI.
  • Basic Git operations and project development experience.
  • Preliminary understanding of Prompt Engineering.

Project Background

Overview

claude-code-best-practice is an open-source reference library designed to enhance collaboration efficiency with Claude Code. It synthesizes fragmented advice from the official Anthropic team (including Claude Code creator Boris Cherny) and practical strategies from community developers handling large monorepos.

Author Introduction

  • Author: shanraisshan
  • Core Philosophy: Advocates for an "Architecture-Driven Model," emphasizing guiding AI through clear specifications rather than simple dialogue.

Project Data

Key Features & Core Modules

Core Modules

  1. Concepts
    • Deep dive into the optimal line count for CLAUDE.md (recommended 60–150 lines) and using .claude/rules/ for path-scoped constraints.
  2. Workflows
    • Introduces advanced workflows like "Cross-Model Collaboration" and "Parallel Git Worktrees."
  3. Tips & Tricks
    • Consolidates over 70 practical tips for Prompting, Planning, and Memory management.
  4. Agent Teams
    • Explores coordinating specialized sub-agents (e.g., a dedicated QA Agent) to review code.

Core Advice

  • Always start with /plan: Before executing any code, have Claude generate a plan and get human confirmation.
  • Manual /compact Mechanism: When context usage exceeds 50%, manually trigger compaction to avoid the AI's "dumb zone."
  • Use <important if="..."> Tags: Ensure rules are strictly enforced using conditional tags as the project grows.

Quick Start

To immediately boost your Claude Code efficiency:

  1. Streamline your CLAUDE.md: Remove redundant descriptions and keep only core architectural definitions and styles.
  2. Configure Custom Hooks: Add scripts under .claude/hooks/ to auto-run tests after code modifications.
  3. Introduce a Task List: Have Claude maintain a live task list under /memories/session/.

Project Advantages

DimensionThis Project (Agentic Engineering)Regular Usage (Vibe Coding)
PredictabilityHigh, via planning and gatingLow, dependent on AI improvisation
Large-scale HandlingStrong, using tiered rules and local contextWeak, easily loses track of global context
AutomationExtremely high, including auto-testsMedium, limited to code generation
CollaborationSupports multi-branch parallel workLimited to single session interaction

Detailed Analysis: Advanced Techniques

1. The Power of Git Worktrees

The project strongly recommends using git worktree. This allows you to assign independent physical paths to different agents. One agent can fix bugs while another develops features on a new branch—each with its own isolated test environment.

2. Cross-Model Quality Assurance

Recommends using two instances of Claude Code: one as an "Implementation Agent" and another as a "Reviewer Agent." The reviewer uses tools like grep_search to find flaws and ensure logical rigor.

3. Progressive Disclosure

Don't dump every document at once. Use a well-structured directory and index to guide the AI to read a module's SKILL.md only when it needs to modify that specific part.

Project Resources

Official Resources

Target Audience

  • AI-Native Developers: Full-stack engineers pursuing peak development efficiency.
  • Team Leads: Managers needing to standardize AI programming norms for their teams.
  • Hardcore Claude Code Users: Those looking to break usage bottlenecks and handle complex business logic.

Welcome to visit my Homepage to find more useful knowledge and interesting products.

← Back to Blog