DEV Community: 马国锦

How I Ship 10x Faster with Claude Code: The 5-Layer Workflow System

马国锦 — Thu, 11 Jun 2026 03:37:23 +0000

After 8 months of daily Claude Code use, I've distilled my workflow into a 5-layer system. Each layer builds on the previous one. Skip one, and the whole thing falls apart.

The Problem with Most Claude Code Users

Most people use Claude Code like ChatGPT — open terminal, ask a question, close, repeat. The next day, they explain their project from scratch. Again.

The symptom: 20% of every session is wasted on context re-establishment.
The root cause: No project memory, no workflow discipline.

Here's the system that fixed it for me.

Layer 1: CLAUDE.md — Your Project's Memory Anchor

This is the foundation. Without it, nothing else works.

CLAUDE.md is a file at your project root. Claude reads it automatically at the start of every session. It tells Claude:

What this project is (one sentence)
The tech stack (specific technologies, not "Python web framework")
The architecture (the big picture you'd need 3 files to understand)
Unique conventions (not generic advice like "write tests")
Quality priorities

Bad CLAUDE.md (you've probably written this):

# My Project
A web application built with Python and FastAPI.

## Development
- Write clean code
- Add unit tests
- Use Git

This tells Claude nothing it doesn't already know.

Good CLAUDE.md:

# CLAUDE.md

## Project Overview
Internal RAG knowledge base serving 500+ employees.

## Tech Stack
FastAPI + LangChain + Milvus + PostgreSQL + Redis

## Commands
- Start: `uvicorn app.main:app --reload --port 8080`
- Test: `pytest -x --cov=app --cov-report=term-missing`

## Architecture
Request flow: router → service → retriever → Milvus
                             → generator → LLM API
Key directories:
- app/router/  - API layer
- app/service/ - Business logic orchestration
- app/retriever/ - Retrieval strategies (vector/BM25/hybrid)
- app/generator/ - LLM calls and prompt management

## Key Conventions
- All APIs return `{"data": ..., "error": null}`
- Retrieval results MUST include source field
- Milvus collection naming: `{env}_{doc_type}`

The rule: Only write what's unique to your project. Claude already knows to use Git.

Layer 2: Plan Mode — Direction Before Speed

Trigger: Any change touching 3+ files or architecture.

How it works:

Claude explores existing code (modules, data flows, API structures)
Designs an implementation plan
Shows you the plan for approval
Only writes code after you confirm

The anti-pattern: "Rewrite the entire auth module" → Claude changes 12 files → everything breaks → you don't know where to start fixing.

The fix: "I want to add hybrid search. Let's plan first." → Claude explores → proposes architecture → you approve → step-by-step implementation.

Layer 3: Small Tasks — One Unit, One Commit

Each task changes ONE logical unit. After each task, the project is still runnable.

Bad:

You: "Refactor the entire retriever module."
Claude: [changes 8 files] → total chaos

Good:

You: "Step 1: Extract BM25 logic into retriever/bm25.py"
Claude: [changes 1 file, tests pass]
You: "Step 2: Add RRF fusion in retriever/fusion.py"
Claude: [changes 1 file, tests pass]
You: "Commit these two steps."

Why this matters: Each commit is a checkpoint. Something breaks? You know exactly which commit introduced it.

Layer 4: Git — Your Undo Button

Commit after every small task. This isn't just version control — it's your change log.

feat: extract BM25 retriever into standalone module
feat: add RRF fusion for hybrid search
fix: Chinese tokenization for BM25 queries

The commit history IS your project journal. Six months later, you can trace why a design decision was made.

Layer 5: Worktree — Parallel Without Collision

When you're working on feature A and need to fix bug B without context-switching:

# While working on feature A...
git worktree add ../bugfix .claude/worktrees/hotfix
cd ../bugfix
# Fix bug B in complete isolation
# Commit, return, clean up
cd -
git worktree prune

Or just tell Claude: "Use a worktree for this." It handles the isolation automatically.

Bonus: Context Compounding — The Meta-Layer

Every technical decision you make, every pattern you discover — write it down. It compounds.

Level	Vehicle	What Gets Stored
Project	CLAUDE.md	Architecture, conventions, decisions
Session	Memory system	User preferences, feedback, corrections
Knowledge Base	Linked notes	Methodologies, patterns, abstractions

After 8 months, my AI assistant doesn't just understand my project — it understands how I think about projects.

Putting It All Together

Here's what adding a "CSV export" feature looks like with this system:

CLAUDE.md      → Auto-loads project context. Claude knows where the API routes live.
Plan Mode      → "Let's plan the CSV export feature first" → Approval before code.
Small Tasks    → Step 1: Add export route. Step 2: Add frontend button.
Git            → Commit after each step. Rollback if needed.
Worktree       → Meanwhile, fix a login bug in isolation.

The result: Features ship faster, bugs are traceable, and every new session starts with full context.

Quick Start Checklist

Day 1: Write a proper CLAUDE.md (30 min — just write the unique stuff)
Day 2: Say "Let's plan first" before cross-file changes
Day 3: Break one big task into 3-5 small steps
Day 5: Try Worktree — "Use a worktree for this"
Day 7: After your first design decision, write a Memory
Day 14: Review two weeks of commits — you'll see patterns worth documenting

Two weeks from now, you won't be "chatting" with Claude anymore. You'll be producing.

If this helped you level up your Claude Code workflow, give it a unicorn. I share more practical AI engineering tips weekly — follow me here on Dev.to.

Build Your RAG System Right the First Time: 6 Decisions That Make or Break It

马国锦 — Thu, 11 Jun 2026 03:36:21 +0000

After debugging 20+ broken RAG systems, I've identified the 6 decisions that determine whether yours works. Here's how to get each one right.

The RAG Developer's Trap

Every RAG developer falls into the same trap: you build the basic pipeline, it sort of works, and then you spend weeks tweaking prompt templates — while the real problem sits untouched in your indexing pipeline.

The 80/20 rule: 80% of RAG problems come from indexing, not generation. But 80% of debugging effort goes into generation.

Let's fix that.

Decision 1: Embedding Model — The Single Biggest Lever

The mistake: Using all-MiniLM-L6-v2 for Chinese documents because it's the default in every tutorial.

Why it's wrong: It's English-trained. Drop it on Chinese text and it loses 30-50% of semantic fidelity.

Language	Use This
Chinese	`BAAI/bge-large-zh-v1.5` (1024-dim)
Chinese + English	`BAAI/bge-m3` (multilingual + sparse)
English	`text-embedding-3-large`
Code	`jina-embeddings-v3` or `voyage-code-3`

Non-negotiable: Indexing model and query model must be byte-for-byte identical. Switch models = rebuild entire index.

Impact: +15-40% Recall@10 for Chinese RAG.

Decision 2: Chunk Size — Not a Magic Number

Physics: Too small (< 100 tokens) = semantic fragmentation. Too large (> 1000 tokens) = noise injection.

Document Type	Sweet Spot	Overlap
FAQ / Short-form	128-256	20
Technical docs	512	50
Long-form articles	768-1024	100
Code	Function boundaries	0

The method matters more than the size. Use recursive splitting, not fixed-length:

from langchain.text_splitter import RecursiveCharacterTextSplitter

splitter = RecursiveCharacterTextSplitter(
    chunk_size=512, chunk_overlap=50,
    separators=["\n\n", "\n", ". ", " ", ""]
)

Impact: +5-15% Recall@10.

Decision 3: Index Type — HNSW vs IVF

Scale	Use	Why
< 1M vectors	HNSW	Recall > 0.95
1-5M, RAM tight	IVF + PQ	75% memory savings
> 5M	IVF + PQ + Sharding	Horizontal scale

Key nuance: HNSW has high insertion cost. Streaming docs → IVF may be better even at small scale.

Impact: +5-15% recall or 2-5x latency improvement.

Decision 4: Metadata — Not Optional

Without metadata filtering, every query scans every vector. Add department=engineering AND date > 2024-01-01 and you go from 5M → 50K vectors.

{"source": "internal_wiki", "doc_type": "design_doc",
 "publish_date": "2024-06-01", "department": "engineering"}

Bonus: Inject metadata into prompts. LLMs weight credibility based on source and recency.

Impact: +10-25% precision from filtering alone.

Decision 5: Deduplication — Do It Twice

Enterprise knowledge bases are full of duplicates. Without dedup, your top-10 results might be 7 copies of the same document.

Document-level (before chunking): MinHash + LSH, threshold 0.85
Chunk-level (after chunking): SimHash, threshold 0.95

Impact: +10-20% effective recall.

Decision 6: Query Processing — The Other Half

Technique	When	Cost
Query rewriting	Short/fuzzy queries	Low
HyDE	Factual Q&A, < 10 words	Medium
Multi-path recall + RRF	Semantic + exact-match	Medium
Cross-Encoder rerank	Post-retrieval refinement	Medium

Minimum viable stack: Query rewriting + Cross-Encoder rerank.

The Optimization Priority Stack

First (biggest impact):
  - Embedding model language-appropriate?
  - Chunk size reasonable (256-768)?
  - Deduplicating?

Second:
  - Query rewriting
  - Cross-Encoder reranking
  - Metadata filtering

Third:
  - Multi-path recall + RRF
  - HyDE for short queries

How to Know If You Fixed It

Don't guess. Measure. 50 (query, ground_truth) pairs, track Recall@10 and MRR.

def recall_at_k(results, ground_truth, k=10):
    return int(ground_truth in [r.id for r in results[:k]])

def mrr(results, ground_truth):
    for i, r in enumerate(results):
        if r.id == ground_truth:
            return 1.0 / (i + 1)
    return 0.0

If this saved you an afternoon of debugging, give it a unicorn and share it with someone who's still tweaking chunk sizes.