A Claude Code Best-Practice Collection: How to Navigate shanraisshan/claude-code-best-practice
Once you start adopting Claude Code at work, there comes a stage where even reading the official documentation makes it hard to see "what to adopt next" and "which one fits my level." The features Anthropic itself ships exceed 30 kinds; the workflows the community publishes number 12 or more; and the tips from Claude Code's developers like Boris Cherny and Thariq are scattered across 80-plus.
What helps organize that is shanraisshan/claude-code-best-practice, which won GitHub Trending #1 in March 2026. It is a repository published and continuously updated under the MIT license by Shayan Raisshan (organizer of the Claude Pakistan community, a Claude Community Ambassador). As of this writing (May 25, 2026), it is a curation collection with 445 files and a 585-line README.
This article is a map that organizes this repository so you can pick out only the elements that match your level and use case. It is a single long piece, but it does not assume you read it through; the structure lets you skim from the table of contents. Where something catches your eye, the important links in the body are direct links to specific files inside the repository so you can jump straight to them on GitHub.
In addition, at the end of each chapter I set up an :::info My implementation examples block that includes how I myself practice it in my ~/.claude/ (7 agents / 38 skills / 31 rules / 3 hook scripts / 1 team / 16 ADRs). I made it usable as a bridge between "someone else's organization (curation)" and "my own harness (implementation)." If you do not need the implementation examples, you can skip the :::info blocks and pick up only the :::note Adoption decision blocks across chapters without breaking the main thread.
This repository positions itself, in the author's own words, as "a reference / course, not a code repo" (the How to Use section of the README). This article follows suit: it first presents the overall picture, then places an Adoption decision mini-summary at the end of each chapter to organize "what will I try." The level-by-level roadmap is collected in the final Chapter 9, so if you are in a hurry you may read from there.
Chapter 1: What the repository really isthe roles of 13 directories
First, grasp the overall picture. Directly under the repository there are 13 main directories and 2 core files.
shanraisshan/claude-code-best-practice/
├── README.md The hub. 585 lines, with all classification tables consolidated
├── CLAUDE.md This repo's own Claude Code config (self-referential)
├── best-practice/ (8 items) Spec catalogs per concept
├── implementation/ (6 items) Working implementation examples
├── orchestration-workflow/ A showcase (Command -> Agent -> Skill)
├── agent-teams/ Agent Teams implementation examples
├── development-workflows/ cross-model + RPI workflows
├── reports/ (12 items) Deep-dive analysis reports
├── tips/ (10 items) Collected remarks from Boris / Thariq and others
├── videos/ (8 items) Podcast / video explanations
├── tutorial/ day0 / day1 setup steps
├── changelog/ Update tracking
├── presentation/ Talk materials from GDG Kolachi and others
└── .claude/ This repo's own agents/commands/skills/hooks
The hallmark of this repository is that four information axes share the roles.
| Axis | Location | Purpose | Value to the reader |
|---|---|---|---|
| Concepts | best-practice/ | Spec catalog of each feature | Grasp "what this feature is" in 5 minutes |
| Workflows | development-workflows/, orchestration-workflow/, links to external repos like ECC/Superpowers | Methodologies that combine features | Learn how others combine them |
| Tips | tips/ + the README's 83 items | An aggregation of developer remarks | Discover what to try next |
| Reports | reports/ (12 items) | Comparative analysis and deep-dive essays | Understand the reasoning of "why do it this way" |
Where to start reading is decided by your own Claude Code experience level. If you just finished installing, start from tutorial/ and move to the beginner Tips categories. If you have run the basic features, read the 8 files in best-practice/ in order while trying one Workflow. If you are already growing your own .claude/, look for your next improvement hints in the comparison of Reports and Workflows — that kind of thing.
Bookmark the directory diagram as a "table of contents." Rather than trying to read it all in one session, skimming chapter by chapter sticks better. Glancing at the Chapter 9 roadmap first and then coming back is also one way to read.
Chapter 2: A catalog of 30+ Claude Code concepts
At the center of the repository are the 🧠 CONCEPTS table and the 🔥 Hot table at the top of the README. They cover the features Anthropic has added to Claude Code, attaching for each feature links to "official documentation," "the best-practice explanation in the repo," "implementation examples," and "community implementation examples."
Here I regroup the features by role to introduce them. I attach an adoption difficulty label to each feature: ★ can be introduced in 1 config file / under 30 minutes of learning, ★★ requires a few files + 1-2 hours of learning, and ★★★ requires combining multiple features / half a day or more of understanding.
2.1 Core primitives (4)
The four basic features that make Claude Code "more than just a chatbot."
Subagents ★★：best-practice/claude-subagents.md explains 16 frontmatter (= YAML metadata written at the top of a file) fields in a table. The fields are name / description / tools / model / permissionMode / skills / mcpServers / hooks / memory / effort / isolation / initialPrompt / color and so on. Anthropic also provides 5 official built-ins, configured as general-purpose (general), Explore (codebase exploration with haiku), Plan (read-only implementation planning), statusline-setup, and claude-code-guide. Implementation examples are collected in implementation/claude-subagents-implementation.md.
At the core of the design is the principle of Generator-Evaluator separation. This is the idea of splitting "the side that makes (Generator)" and "the side that evaluates (Evaluator)" into separate subagents to avoid self-evaluation bias (= the cognitive bias of overestimating quality when you evaluate what you made yourself). Boris Cherny mentions it repeatedly too.
Commands ★：How to make slash commands is explained in best-practice/claude-commands.md. Just placing Markdown in .claude/commands/<name>.md lets you call it as /<name> — the lowest-cost extension point. In Boris Cherny's tips too, "make any task you do at least once a day a command or skill" is repeatedly emphasized.
Skills ★★：In best-practice/claude-skills.md, in addition to 15 frontmatter fields, 9 official bundled skills are tabulated. First are the 5: simplify (deduplication refactoring), batch (bulk commands), debug (failure investigation), loop (scheduled execution), and claude-api (Anthropic SDK assistance). The remaining 4 are fewer-permission-prompts (auto-generate an allowlist), run (launch the real app), verify (behavior verification), and run-skill-generator (create a launch recipe). What is especially new is that v2.1.145 added 3 — /run, /verify, and /run-skill-generator.
An important concept in skill design is progressive disclosure. Rather than cramming all the information into one SKILL.md file, you place references/ scripts/ examples/ inside the folder and structure it so Claude loads them only when needed. This is a design guideline for not pressuring the context window (the token budget that can be processed at once).
Hooks ★★★：A mechanism to run shell commands on lifecycle events like PreToolUse / PostToolUse / Stop / SessionStart. Within the repo it stands alone as a separate repo, shanraisshan/claude-code-hooks, with implementation examples like sound notifications / auto-formatting / blocking dangerous commands. Boris's remark, "putting auto-format in a PostToolUse hook lets Claude finish the last 10% of the code it generates and prevents CI failures," is a representative use.
A framework for organizing hooks' roles is the dichotomy of Computational Sensor / Inferential Guide. A Computational Sensor is "a deterministic mechanism that auto-detects in code" (lint / CI / a hook's suppression detection, and so on). An Inferential Guide is "a probabilistic mechanism that lets the LLM judge for itself" (the instruction text of CLAUDE.md / rules / skills). A hook handles the former, and plays the role of deterministically enforcing norms that the LLM would violate probabilistically with rules or CLAUDE.md alone.
So far we have seen Subagent / Command / Skill / Hook, but let me consolidate into one table the boundary of Subagent vs Skill vs Command, which beginners find most confusing (Hooks are a lifecycle mechanism, so I organize them on a separate axis).
| Feature | Role | How to launch |
|---|---|---|
| Command | Entry point / workflow conductor | The user types /<name> |
| Agent (Subagent) | The lead for domain work (runs in a separate context window) | Called from a Command or an upper agent |
| Skill | A unit of deliverable generation / reference knowledge | Auto-launched by a trigger utterance, or called from the Skill tool |
~/.claude/)I place 7 subagents in ~/.claude/agents/, intentionally building in Generator-Evaluator separation. The breakdown is the 7: architect / code-reviewer / debugger / implementer / refactorer / test-strategist / infra-reviewer.
- Generator (the making side): implementer (implementation only) / refactorer (refactoring only) / debugger (bug investigation + fix)
- Evaluator (the evaluating side): architect (design review) / code-reviewer (code review) / test-strategist (test strategy) / infra-reviewer (TF/IaC review)
The 4 on the Evaluator side enforce read-only with disallowedTools: Write, Edit, structurally preventing the evaluators from mistakenly reaching into the implementation. For naming too, instead of generic names like general qa, I unify on Boris's recommended feature-specialized (concrete role names).
Concretely, the frontmatter of a subagent definition file is written in YAML like the following (an excerpt from my code-reviewer.md).
---
name: code-reviewer
description: A code reviewer for pair programming. Provides review and guidance after code changes
model: opus
effort: max
tools: Read, Grep, Glob, Bash, WebSearch, mcp__context7__query-docs
disallowedTools: Write, Edit
isolation: worktree
---
# Instruction body...
By making allowed tools explicit with tools and forbidden tools explicit with disallowedTools, you can deterministically eliminate the risk of an evaluation-only agent mistakenly reaching into the implementation.
I run with 0 Commands, consolidating all uses into skills. The reason is that a skill can be auto-launched by a trigger utterance (e.g., "review," "bug") written in its frontmatter, saving the trouble of typing /command-name every time. Boris's "make any task you do at least once a day a command or skill" is, in my environment, translated into "make everything a skill."
Skills are 38 folders (propose / debug / review / explain / compare / learn / next / checkpoint / spec-driven-development / verify and more). The mapping of representative trigger utterances is as follows.
| Skill | Trigger utterance | Role |
|---|---|---|
/propose | "propose," "design draft" | Proposes an implementation approach with adversarial self-critique (up to 2 iterations) |
/debug | "bug," "not working" | Autonomously resolves with Investigate -> Fix -> Verify in up to 3 iterations |
/review | "review," "check" | Code review from 7 perspectives (correctness / readability / performance / security / maintainability / conventions / regression) |
/explain | "explain," "why" | Explains code or a concept step by step |
/checkpoint | "checkpoint," "break here" | Organizes the current session + generates a prompt for the next session |
The progressive-disclosure structure (folder type with references/ scripts/ examples/) is only 2 (skill-creator / react-view-transitions). The other 36 get by with SKILL.md alone + metadata, on a policy of introducing the structure incrementally as needed.
Hooks are 3 actual scripts I run.
~/.claude/hooks/check-protected-files.sh(PreToolUse)：blocks writes to protected files like.envbefore Write/Edit runs~/.claude/hooks/check-suppression.sh(PostToolUse)：deterministically verifies whether a suppression was newly added to Write/Edit output. Targets are things like// eslint-disable-next-lineand// @ts-ignore~/.claude/hooks/check-plain-question.sh(Stop)：greps the text output at response end and detects plain-question patterns like "shall I...?" and "is it...?". It urges Claude to self-correct with exit 2 (a Sensor that enforces use of the AskUserQuestion tool)
That I repurpose Boris's "auto-format in a PostToolUse hook" into "suppression detection" rather than "format" is an intentional difference. Format is sufficiently covered by CI, but suppression is an anti-pattern the LLM inserts probabilistically, and once it persists after passing CI it hollows out the harness, so I block it immediately right after execution with a PostToolUse hook.
2.2 Integration mechanisms (5)
A layer for connecting to the outside world and project configuration.
| Feature | Difficulty | In-repo reference |
|---|---|---|
| MCP Servers | ★★ | best-practice/claude-mcp.md：a protocol to call context7 / aws-knowledge / playwright and the like from Claude Code |
| Plugins | ★★ | official docs：distributable packages. Also links how to stand up a marketplace |
| Settings | ★ | best-practice/claude-settings.md：covers all fields of .claude/settings.json, permission / model / output style, etc. |
| Status Line | ★ | shanraisshan/claude-code-status-line：visualize context usage / cost |
| Memory | ★★ | best-practice/claude-memory.md + deep-dive reports/claude-agent-memory.md：the hierarchy of CLAUDE.md / .claude/rules / auto-memory |
Here let me add a bit about MCP (Model Context Protocol). It is "a standard protocol Anthropic defined for letting Claude call external tools and data sources." Introduce a corresponding MCP server, and Claude can call external features as tools. For example, fetching library docs (context7) / fetching official AWS docs (aws-knowledge) / browser automation (playwright / chrome-devtools) / codebase symbol search (serena), and so on. Because you can reliably obtain primary sources that WebSearch alone would miss, the accuracy of technical judgment improves.
2.3 Session control (3)
Mechanisms for Claude Code to "keep acting smartly" in long sessions and complex tasks.
- Checkpointing ★：Auto-tracks file edits and lets you go back to a past state with
/rewind. It gains value combined with Thariq's tip that "rather than polluting the context with a failed attempt, it is better to rewind." - CLI Startup Flags ★：A list of major flags in best-practice/claude-cli-startup-flags.md.
--permission-mode,--agent,--bg,--worktree, etc. - Auto Mode / Plan Mode ★★：
Shift+Tabcycles the modes Ask -> Plan -> Auto. Auto Mode is a mechanism where a model-based classifier (= a classifier that auto-categorizes command safety with a small model) judges each command's safety and auto-approves, and Boris recommends "use this instead of dangerously-skip-permissions."
2.4 🔥 Hot features (new features, high priority)
A group of features added rapidly in 2026. Some are marked beta and may change spec, but I introduce ones with large room for use at work.
| Feature | Difficulty | Purpose |
|---|---|---|
| Ultrareview ★★ | beta | Multi-agent PR review with /ultrareview. Specify a GitHub PR# and run it, and review runs in parallel from multiple perspectives |
| Ultraplan ★★ | beta | Large-scale planning with /ultraplan. A superior version of Plan mode |
| Auto Mode ★ | beta | See §2.3 above. The classifier auto-approves safe commands |
| Power-ups ★ | — | /powerup (best-practice/claude-power-ups.md) |
| Fast Mode ★ | beta | Speed up output with /fast (does not downgrade the model; usable on Opus 4.6/4.7) |
| Chrome ★★ | beta | Claude-dedicated Chrome extension integration with --chrome. Share login state of Payload admin and the like to operate |
| Code Review ★ | beta | Provided as a managed GitHub App. Boris mentions it "replaces Greptile / CodeRabbit / Cursor BugBot" |
| GitHub Actions ★★ | — | Call claude in .github/workflows/. GitLab CI/CD is also supported |
| Remote Control ★★ | — | Headless (= run without a GUI) operation with /remote-control / /rc |
| Agent Teams ★★★ | beta | Launched via an env var, running multiple agents in parallel (implementation/claude-agent-teams-implementation.md) |
| Scheduled Tasks ★★ | — | /loop (local, up to 7 days) and /schedule (cloud cron) (implementation/claude-scheduled-tasks-implementation.md) |
| Routines ★★ | beta | A scheduled agent that runs in the cloud. Runs even when the machine is off |
| Goal ★★ | — | "Auto-iterate turns until a condition is met" with /goal <condition> (implementation/claude-goal-implementation.md) |
| Voice Dictation ★ | beta | Voice prompts with /voice |
| Computer Use ★★★ | beta | The computer-use MCP server. Automating desktop operation |
| Git Worktrees ★★ | — | Parallel development with --worktree / -w. Boris introduces 5 ways to use it |
| Simplify & Batch ★ | — | The /simplify / /batch bundled skills |
| Ralph Wiggum Loop ★★★ | — | A plugin. A long-running autonomous loop. The implementation is published in a separate repo |
By the way, Git Worktrees in the table is the standard git feature of "checking out the same repository into a separate directory for parallel work" (used like git worktree add ../feature-x feature-x). Claude Code's --worktree flag and a subagent's isolation: worktree setting use this feature to isolate work from the main workspace.
~/.claude/)I do not use the --worktree flag itself much, but I do adopt the pattern of launching subagents (debugger / refactorer / code-reviewer) with isolation: worktree1. It isolates reviews and refactors — which tend to be long or destructive — from the main workspace, making rollback on failure safe.
Auto Mode I use for its permission-prompt reduction effect. For cases where the classifier blocks during auto-implementation after Plan mode approval, I set up a flow that asks me for explicit authorization via the AskUserQuestion tool (Phase 13 W1-1 ratchet). This flow comes from the norm in ~/.claude/rules/ask-user-question.md. It is a design that absorbs the authorization gap between Auto Mode's convenience and destructive operations with the harness.
When in doubt, introduce from ★ first. Plan Mode, Commands, and Settings work from day one. The ★★ Subagents / Skills / Hooks are areas where making one over the next weekend yields large progress. For ★★★ (Agent Teams / Computer Use / building your own Hooks / Ralph Wiggum), the safe order is to take them on after combining the basic features and getting a feel.
Chapter 3: The Orchestration Workflow showcase
Placed at the center of this repo is a 3-layer orchestration: Command -> Agent -> Skill. The author demonstrates it with a weather-data-fetching workflow called /weather-orchestrator (orchestration-workflow.md).
There are two design points this showcase conveys.
The first is the distinction between two Skill patterns. weather-fetcher is specified in weather-agent's frontmatter via the skills: field and is injected in full into the context the instant the agent launches (the Agent Skills pattern). On the other hand, weather-svg-creator is not preloaded and fires only when the command calls the Skill tool (the Skill pattern). Remember the former as "giving the agent domain knowledge as a skeleton" and the latter as "creating a deliverable," and it falls into place.
The second is thorough role division. The Command conducts the workflow, the Agent handles domain work like data fetching, and the Skill outputs the deliverable. Because the three layers line up with single responsibilities, later changes like "swap the fetcher to OpenWeather" or "output PNG instead of SVG" stay localized. The implementation files can be referenced directly at .claude/commands/weather-orchestrator.md and .claude/agents/weather-agent.md. The skill side is .claude/skills/weather-fetcher/SKILL.md and .claude/skills/weather-svg-creator/SKILL.md.
Clone the repo and run /weather-orchestrator, and you can reproduce the above flow on your own machine as-is. As material for learning the 3-layer structure, this is the easiest thing in the repo to get your hands on.
~/.claude/)With the same "3-layer orchestration" idea as the weather example, I build a team configuration called ~/.claude/teams/multi-perspective-review/. The difference is that whereas the weather example is serial execution of heterogeneous roles ("Command -> Agent -> Skill"), this is parallel execution of homogeneous Evaluator agents.
- Team composition: Launch 3 Evaluator subagents：
code-reviewer+architect+test-strategist— in parallel - Trigger utterances: "review from multiple perspectives," "comprehensive review," "3 perspectives" (recommended for changes of 10+ files)
- Integration: The main agent integrates the judgments each agent produced independently and presents them to me after organizing duplicate findings
The design goal is "to redundantly verify, from 3 independent perspectives, large changes where a single Evaluator would miss things." In contrast to the weather example's "assembling a routine task serially," this is for "redundifying important judgment in parallel," usable as a case showing the broad applicability of the 3-layer structure.
Also, even in environments where the Agent Teams feature is disabled, I record a fallback path via the Task tool (the main agent calls the 3 subagents sequentially) in team.md, building in resilience to feature changes.
The quickest way to understand this pattern is to clone the weather example and run it as-is. In your own work too, try rewriting just one task that finishes in 3 steps — like "routine report generation" or "data fetching + visualization" — in this 3-layer structure, and the pattern sinks in.
Chapter 4: Comparing 12 development workflows
The README's ⚙️ DEVELOPMENT WORKFLOWS section lines up 12 major workflows published in the community in star order for comparison. Each workflow is "a methodology for advancing development by chaining multiple slash commands or skills," and each has a different philosophy and granularity.
| Workflow | ★ | Flow characteristics | Composition (A / C / S) | Suited to |
|---|---|---|---|---|
| Superpowers | 200k | brainstorming -> worktrees -> writing-plans -> subagent-driven -> TDD -> code-review -> verification -> finishing | 0 / 0 / 14 | People who emphasize TDD + parallel development |
| Everything Claude Code (ECC) | 188k | /ecc:plan -> /tdd -> /code-review -> /security-scan -> /e2e -> merge | 48 / 143 / 230 | Full-set adoption for a commercial product |
| Spec Kit | 104k | /speckit.constitution -> .specify -> .clarify -> .plan -> .tasks -> .implement | 0 / 9 / 0 | Experiencing a minimal spec-driven setup |
| gstack | 100k | /office-hours -> 3 kinds of /plan-*-review -> /design-shotgun -> /review -> /ship -> /retro | 0 / 0 / 48 | Running multi-angle CEO/Eng/Design review |
| Matt Pocock Skills | 97k | /grill-with-docs -> /to-prd -> /to-issues -> /triage -> TDD -> /diagnose -> /improve-codebase-architecture | 0 / 0 / 28 | Carefully going from requirements to PRD |
| Get Shit Done | 63k | /gsd-new-project -> discuss -> plan -> execute -> verify -> ship -> complete-milestone | 33 / 67 / 0 | Solo development seeking speed |
| OpenSpec | 50k | The 3 stages /opsx:propose -> :apply -> :archive | 0 / 11 / 0 | Minimal spec-driven in just 3 stages |
| BMAD-METHOD | 48k | product-brief -> PRD -> architecture -> epics-and-stories -> sprint-planning -> story-by-story implementation | 0 / 0 / 42 | Teams collaborating with PdM/PM |
| oh-my-claudecode | 34k | /deep-interview -> /team -> 5-stage team flow -> /ralph -> merge | 19 / 0 / 39 | People who want Team mode and the Ralph loop |
| agent-skills | 27k | /spec -> /plan -> /build -> /test -> /review -> /ship | 3 / 7 / 21 | The standard 6 stages; start here when in doubt |
| Compound Engineering | 17k | /ce-ideate -> brainstorm -> plan -> work -> code-review -> debug -> optimize -> compound | 49 / 4 / 38 | Wanting a companion from the idea-divergence stage |
| HumanLayer | 11k | /create_plan -> /validate_plan -> /implement_plan -> /iterate_plan -> /local_review -> /commit | 6 / 27 / 0 | Strictly separating plan validation and iteration |
A = Agent / C = Command / S = Skill counts. The abbreviations in the table are as follows. TDD = Test-Driven Development (writing tests before implementing). PRD = Product Requirement Document. RPI = Research-Plan-Implement (the 3-stage pattern of research -> plan -> implement).
Lining up the flows of all 12, even if the granularity and names of the components differ, you can see that they all converge on roughly the same pattern: Research -> Plan -> Execute -> Review -> Ship. This is a point the author himself emphasizes in the README, and it also matches the observational fact that the more veteran you are, the more naturally you settle into these 5 stages.
Let me offer a few ways to look at it when choosing a workflow. Spec Kit is a minimal setup that completes with just 6 slash commands, suited to first experiencing "the spec-driven flow." Everything Claude Code (ECC) is ultra-large-scale at 48 agents + 143 commands + 230 skills, for people who want full-set adoption for a commercial product. BMAD-METHOD is composed in "the language of management" — PRD -> architecture -> sprint planning — so it suits teams collaborating with PdMs and PMs. Matt Pocock Skills features a flow of pinning down requirements with /grill-with-docs before turning them into a PRD, and combined with Matt's own YouTube explanation, understanding comes fast (in-repo videos/claude-matt-pocock-24-apr-26.md).
As methodologies original to the repo, the development-workflows/ directory has its own Cross-Model Workflow (cross-model-workflow.md) and RPI Workflow (rpi-workflow.md). RPI is an implementation of the research-plan-implement pattern combining a Plan agent with 8 kinds of specialist agents. The specialist agents are constitutional-validator / requirement-parser / ux-designer / senior-software-engineer and so on. The actual files are in the repo's .claude/agents/, so you can reference them as-is.
~/.claude/)I do not adopt any of the 12 workflows in the table wholesale. Instead, grounded in the paper evidence of Plan-and-Solve (ACL 2023) / Plan-and-Act (ICML 2025), I adopt a norm called the plan-then-execute Workflow Gate. I made it a harness norm in ~/.claude/rules/plan-then-execute.md. It is a simple gate: "for tasks involving 3+ files / unfamiliar territory / architecture judgment / irreversible changes, always separate a Plan phase before starting implementation."
For the 4-phase structure of SPECIFY -> PLAN -> TASKS -> IMPLEMENT itself, I run the spec-driven-development skill from addyosmani/agent-skills (MIT), which is not among the 12 in the table. I have already taken this skill into ~/.claude/skills/spec-driven-development/. Because the skill auto-launches on a trigger utterance ("spec-driven," "proceed from the spec"), I do not need to type from /specify.constitution by hand like Spec Kit.
My policy is "taking in workflows per-skill and combining them with my own rules" rather than "adopting a workflow from outside wholesale," which is a unique style different from any workflow in the table. For things like BMAD-METHOD's PRD -> architecture flow or Get Shit Done's discuss -> plan -> execute, if I referenced any part, I leave a comment in the relevant skill's individual description.
If you adopt just one, I recommend Spec Kit (simple, just 6 commands) or ECC (comprehensive, commercial-oriented). For team adoption, BMAD-METHOD; for solo work seeking speed, Get Shit Done is also a candidate. Trying several and keeping only the one that clicks helps it stick.
Chapter 5: Skill / Agent collectionsborrowing a library
Beyond workflows, there are also many repos that distribute individual SKILL.md / agent.md as a "library." The README's 🧰 SKILL COLLECTIONS and 🤖 AGENT COLLECTIONS sections organize these.
Skill collections (8, in star order):
| Repo | ★ | Skill count |
|---|---|---|
| anthropics/skills | 138k | 17 |
| mattpocock/skills | 97k | 24 |
| wshobson/agents | 36k | 155 |
| impeccable | 27k | 1 (references 7 design domains) |
| addyosmani/agent-skills | 27k | 21 |
| scientific-agent-skills | 25k | 138 |
| awesome-agent-skills | 22k | 1,100+ (a curated list) |
| claude-skills | 15k | 246 (across 9 domains) |
Agent collections (2):
| Repo | ★ | Agent count |
|---|---|---|
| msitarzewski/agency-agents | 105k | 144 |
| VoltAgent/awesome-claude-code-subagents | 20k | 151 |
There are two points for how to choose. One is domain-specialized vs general-purpose. For design work, impeccable; for research use, scientific-agent-skills provide SKILL.md optimized for the individual domain. For general purposes, putting in Anthropic's official anthropics/skills and Matt Pocock's mattpocock/skills covers daily work.
The other is maintenance frequency. Because Claude Code itself updates frequently, repos that have stopped updating for over six months may have outdated frontmatter fields. The README's tables are built so you can grasp not only star count but also update timing, so when choosing a collection, it is safe to also check the original repo's commit history.
~/.claude/)I do not adopt external collections wholesale; I run my own 38 skills + 7 agents + 1 team. The reasons are these two points.
- Customizing trigger utterances is necessary: I want to finely set each skill's auto-launch condition (Japanese utterances like "review this," "bug") to match my own typing habits, and bringing in external skills tends to mean re-editing all the descriptions
- The intentional design of Generator-Evaluator separation: As stated in Chapter 2.1, the agent group is intentionally built with role-based separation of "3 making / 4 evaluating." External agent collections often lean toward either "all generalists" or "all specialists," and you cannot take in the design philosophy along with them
That said, "in-house vs external" is not a binary; I pick and choose per skill. For example, the spec-driven-development skill touched on in the previous chapter is one I took in from addyosmani/agent-skills (MIT), used in combination with my own rule (~/.claude/rules/plan-then-execute.md). Rather than introducing the whole collection, the realistic approach is "take in only the skills you like, one at a time, and align them with your own environment."
If you need domain specialization, use a dedicated collection (impeccable / scientific-agent-skills, etc.); otherwise, just the two anthropics/skills + mattpocock/skills is plenty practical. awesome-agent-skills is a curated list of 1,100+, so use it as an entrance to find "what else is out there."
Chapter 6: Cross-Model Workflowsmixing other models into Claude Code
The README's 🔀 CROSS-MODEL WORKFLOWS section classifies ways to combine Claude Code with Codex / Gemini / GPT / Kimi / DeepSeek / local models and the like into 3 approaches.
| Approach | Concept | Representative repo |
|---|---|---|
| Plugin | Call another model's CLI from within Claude Code (/codex:review, etc.) | openai/codex-plugin-cc (18k★) |
| MCP | Claude Code calls another model as a "tool" | BeehiveInnovations/pal-mcp-server (12k★, supports 50+ models incl. Gemini / OpenAI / Azure / Grok / Ollama / OpenRouter) |
| Router | Redirect Claude Code's API endpoint to a different provider | musistudio/claude-code-router (34k★), router-for-me/CLIProxyAPI (32k★) |
The repo's own methodology development-workflows/cross-model-workflow/cross-model-workflow.md recommends a "manual 2-terminal flow" doing Plan in Claude Code and QA-Review in Codex. This depends on neither Plugin / MCP / Router and can be tried immediately.
~/.claude/)I intentionally do not adopt cross-model. I use Anthropic's in-house model group (Opus 4.7 / Sonnet 4.6 / Haiku 4.5) apart via a subagent's model: field and Fast Mode (/fast). Combined with adaptive thinking (effort level low/medium/high/xhigh/max), I judge that the balance of needed reasoning depth and cost is taken care of.
Introducing a cross-provider router (musistudio/claude-code-router, etc.) greatly raises the operational load: double management of pricing schemes / regression tracking of compatibility with Anthropic's official features / verifying quality differences per use / increased complexity of API-key management. Because the return that justifies this (e.g., cutting cost to 1/10 with DeepSeek) is not clear in my work, I currently continue Anthropic-only operation.
If I were to adopt it in the future, the first candidate would be the router approach (routing a backup to OpenRouter via claude-code-router). The Plugin approach (calling Codex as /codex:review via openai/codex-plugin-cc) is something I would consider if scenes needing cross-model QA review increase — that is the temperature.
As for in-house Anthropic routing, I make effortLevel: xhigh the default. For 28 subagents / skills like architect / debugger / propose, I build the fine distinction in the harness of overriding to effort: max in frontmatter. Details are touched on in the Workflows Advanced category of Chapter 7.
If you want to integrate major models within Claude Code, the Plugin (openai/codex-plugin-cc). If you want to optimize cost, the Router (route to OpenRouter / DeepSeek / Ollama via musistudio/claude-code-router). If you want to keep Claude as the lead and have other models do QA review, the MCP (pal-mcp-server) — thinking with this division makes it easier to choose.
Chapter 7: An overview of 83 Tips in 15 categories
The README's 💡 TIPS AND TRICKS (83) section tabulates Tips gathered from developers and the community, split into 15 categories. The sources are Boris Cherny (Claude Code developer) / Thariq (Anthropic) / Cat Wu / Dex Horthy / Lydia Hallie / the community, and so on. Each Tip has a direct link to the original tweet or video so you can trace it with its context.
I take up the categories and counts, plus one or two emblematic Tips each.
| Category | Count | Emblematic Tip |
|---|---|---|
| Prompting | 3 | "grill me on these changes — have Claude test before you make a PR" (Boris) |
| Planning/Specs | 7 | "always start with plan mode" (Boris), "have Claude interview you with AskUserQuestion to draw out the spec" (Thariq) |
| Context | 5 | "context rot occurs around ~300-400k tokens" / "the dumb zone is ~40% context — newcomers 40%, veterans defend 30% or below" (Thariq / Dex) |
| Session Management | 6 | "new task = new session" / "/compact vs /clear is a trade-off" (Thariq) |
| CLAUDE.md + rules | 8 | "CLAUDE.md should be 200 lines or fewer; humanlayer is 60 lines" / "lazy-load with paths: frontmatter" |
| Agents | 4 | "make feature-specialized subagents; do not make general qa or general backend" (Boris) |
| Commands | 3 | "make any task you do at least once a day a skill or command" (Boris) |
| Skills | 9 | "skills are folders, not files — progressive disclosure with references/, scripts/, examples/" / "the Gotchas section is the most important; accumulate Claude's failure points" (Thariq) |
| Hooks | 5 | "auto-format in a PostToolUse hook — finish the last 10% of the code Claude generates and prevent CI failures" (Boris) |
| Workflows | 5 | "thinking mode true + Output Style Explanatory makes decisions visible" (Boris) |
| Workflows Advanced | 9 | "/sandbox cuts permission prompts -84%" / "dynamically tune Opus 4.7's effort level with low / medium / high / xhigh / max" (Boris) |
| Git / PR | 5 | "PR p50 is 118 lines — the median of 141 PRs / 45K lines per day" / "always squash merge" (Boris) |
| Debugging | 6 | "hand Claude a screenshot" / "agentic search (glob + grep) beats RAG — Claude Code tried a vector DB and discarded it" (Boris) |
| Utilities | 5 | "iTerm / Ghostty / tmux > IDE" (Boris) |
| Daily | 2 | "update Claude Code daily" / "read the CHANGELOG in the morning" |
To the right of each category there are links to Boris's / Thariq's original posts so you can check the original context. In particular, tips/claude-boris-6-tips-16-apr-26.md (the latest 6 Tips related to Opus 4.7) collects content directly tied to running Claude Code as of 2026. The same goes for tips/claude-thariq-tips-16-apr-26.md (Session Management and mastering 1M context).
Among the Tips are some marked 🚫👶 (do-not-babysit). This is an icon to distinguish "leave it to Claude without nitpicking"-type Tips. Representative examples are grill me, saying just fix, use subagents to throw more compute at it, automating Code Review, and auto-generating a review lint rule with @claude. It is positioned for people advancing to the stage of "trust Claude and let go."
The hidden Tips extracted from the CLI binary are collected in reports/claude-spinner-verbs-and-tips.md. There you can also pick up spinner verbs used inside the CLI but not in the official README (Pondering, Cogitating, Synthesizing, etc.) and related Tips.
~/.claude/)Let me summarize my implementation against the Tips of the main 5 categories in a contrast table.
| Category | shanraisshan's emblematic Tip | My implementation (~/.claude/) |
|---|---|---|
| CLAUDE.md + rules | "CLAUDE.md should be 200 lines or fewer" | 436 lines (over 2x the recommendation, but intentional). The details are dispersed across 20 path-scoped rules + 30 references/ files. The always-loaded portion is held down to 10 files / 722 lines |
| Skills | "the Gotchas section is the most important" | I implement "When to Use" / "Loading Constraints" sections in SKILL.md of doubt-driven-development / mcp-builder / grill-me, etc. |
| Hooks | "auto-format in a PostToolUse hook" | Repurposed into suppression detection (check-suppression.sh) + plain-question detection (check-plain-question.sh) rather than format |
| Agents | "make feature-specialized subagents" | All 7 — architect / code-reviewer / debugger, etc. — are specialized names, zero generalists |
| Workflows Advanced | "dynamically tune effort level with low / medium / high / xhigh / max" | Make effortLevel: xhigh the default in ~/.claude/settings.json, and override per-skill with effort: max in frontmatter (28 files incl. architect / debugger / propose) |
Here let me add four supplements.
The Gotchas / Loading Constraints sections are called "the most important" in the Tips because clarifying "conditions under which this skill fails / scenes where it must not be used" in the SKILL.md body keeps Claude from misjudging launch. Excerpting a real example from my ~/.claude/skills/grill-me/SKILL.md, it has a structure like the following.
---
name: grill-me
description: A skill that pins down requirements / design with tough questions to eliminate ambiguity...
---
## When to Use
- Improving requirement resolution before starting a task
- Scenes where implementing with an ambiguous spec causes large rework
## Gotchas (scenes where it must not be used)
- During already-instructed ongoing work -> it becomes excessive questioning
- Pure fact-checking (resolvable with Read / Grep) -> a single AskUserQuestion is enough
## Loading Constraints
- Skip recommended when context exceeds 50k tokens (interrogation pressures the context)
- Do not interrupt when another skill is in_progress
Sectioning ## Gotchas and ## Loading Constraints like this lets Claude structurally judge "should I launch this skill now." Conversely, without it, the skill tends to misfire in inappropriate scenes.
Path-scoped rule (lazy-load) is a method of writing a glob like paths: ["**/*.ts"] in a rule file's frontmatter. The rule auto-loads only when Claude reads a file matching that glob. The frontmatter looks like this.
---
paths: ["**/*.ts", "**/*.tsx"]
---
# TypeScript Strict Mode norm
- The `any` type is forbidden
- ...
Making it always-loaded pressures the context window, but path-scoping injects only what is needed into the context: during frontend work only the frontend rules, during infra work only the terraform rule. I path-scope 20 of 31 (64%) to effectively circumvent the 200-line constraint.
Effort level is a parameter for dynamically switching reasoning depth on Opus 4.7 (low / medium / high / xhigh / max). Anthropic officially recommends xhigh as the default for coding/agentic tasks. max is said to not be a daily default due to the risk of overthinking + diminishing returns (= the phenomenon where the effect plateaus as you increase input). I override to max in frontmatter only for important judgment (architect / debugger / propose, etc.), getting accuracy in scenes that need deep reasoning while keeping cost efficiency.
Ratchet appears frequently in the Tips. This is the principle of "when you make the same failure twice, always persist it into one of rules / hooks / learnings, making recurrence structurally impossible," which I made a norm in my harness as ~/.claude/rules/ratchet-workflow.md. The idea is that when Claude repeats the same mistake, rather than scolding it by prompt each time, you build it into a deterministic sensor (hook) or inferential guide (rule) to "prevent it with a mechanism next time."
By the way, my ~/.claude/learnings/ accumulates 14 files / 4,363 lines of insights, categorized into core / frontend-vue / frontend-react / infra. With the /learn skill's trigger utterances ("add this," "remember this"), I persist them one at a time, immediately.
Rather than reading all 83 at once, pick up only the category you are currently struggling with. People wrestling with Context or Session Management can set their direction from Thariq's 16/Apr/26 summary alone. People who want to try Opus 4.7 or Auto Mode should prioritize Boris's 16/Apr/26 summary. Take the 🚫👶-marked Tips as for intermediate users and up.
Chapter 8: The 12 Reportsa map of deep-dive material
The reports/ directory holds 12 deep-dive analyses. If Tips are "knowledge you memorize as bullet points," Reports are "reading material where you understand the reasoning in prose."
| Report | Purpose | For readers like this |
|---|---|---|
| why-harness-is-important | A rebuttal to "features are the same as a prompt" (a 10-capability table) | People doubting the value of a harness |
| claude-agent-memory | A detailed explanation of memory's 3 scopes (user/project/local) | People who want to persist cross-session knowledge |
| claude-global-vs-project-settings | The 6-level config hierarchy + Tasks system | People who want to sort out personal / team / org config boundaries |
| claude-agent-command-skill | The boundaries of the 3 features (agent / command / skill) | People unsure "which to use" |
| claude-skills-for-larger-mono-repos | A skill-placement strategy in a monorepo | People handling multiple packages |
| claude-in-chrome-v-chrome-devtools-mcp | Choosing between browser MCPs (Claude in Chrome vs Chrome DevTools) | People who want Claude to operate the browser for frontend / E2E |
| llm-day-to-day-degradation | Tracking and verifying the model "degradation" phenomenon | People who feel "Claude seems dumber lately" |
| claude-usage-and-rate-limits | The structure of rate limits and per-plan caps | People managing cost for work use |
| claude-advanced-tool-use | Advanced patterns of tool use | People implementing custom tools |
| claude-agent-sdk-vs-cli-system-prompts | The system-prompt diff of Agent SDK vs CLI (110+ fragments) | People building their own agent with the SDK |
| claude-spinner-verbs-and-tips | Hidden tips extracted from the CLI binary | People who want to deep-dive into Claude Code |
| learning-journey-weather-reporter-redesign | The design-rethinking process of the weather example | People learning the orchestration pattern |
A single deep dive: why-harness-is-important.md
If I pick the one to read first among the 12, it is why-harness-is-important.md. It is an essay that organizes, in table form, a rebuttal to the reduction that "skills / commands / subagents / hooks are all prompts that ultimately reach the model anyway, so writing one strong prompt yields the same result."
Summarizing the core of the argument:
- For single-shot tasks (e.g., "write a recursive flatten function"),
Output quality ≈ Prompt qualitydoes hold. This is the world of chatbots. - But in real software development, the relationship is
Output quality = f(effective context, model capability, iteration loop). Effective context (what the model sees at inference time) is far larger than the prompt the user typed. - The harness's role is to convert the 6-token prompt the user typed into 5,000-50,000 tokens of effective context at inference time.
- There are 10 capabilities only a harness can provide. For example, context isolation (a subagent runs in a separate window) and harness-enforced tool restrictions (deny settings like
disallowedToolsblock the model before it uses a tool). Also lazy-loaded rules (paths:frontmatter), hooks' deterministic execution, model routing viamodel:, and subagent parallelism come up. Further, cross-session persistence via memory and a modular system prompt (conditionally loading 110+ fragments inside the CLI) apply. The last are skill preloading and the Auto mode permission classifier. These cannot be substituted by strong wording.
Here let me add a bit about the important concept of effective context. This is not "the prompt the user typed itself" but "the totality of information the model actually sees at inference time — the sum of the CLAUDE.md / rules / skills / agent definitions / memory / MCP output that the harness injects behind the scenes." It is the harness's role that a 6-token prompt swells into 5,000-50,000 tokens of effective context. This is why the reduction that "writing rules in strong wording is enough" cannot substitute for it.
Reading this report first makes it easier to grasp, as reasoning, why the feature group introduced in Chapters 2-4 exists. For the remaining 11, choosing according to your interest is fine. If you struggle with memory, pick claude-agent-memory; if you want to organize the settings hierarchy, pick claude-global-vs-project-settings. If you are considering browser automation, claude-in-chrome-v-chrome-devtools-mcp — that kind of thing.
~/.claude/)I have grown my ~/.claude/ as a staged evolution of Phases 0-13. Phase is my own term, a unit of operation for "adding rules / hooks / skills / agents at each milestone and verifying their necessity," rather than completing the harness in one go. Representative milestones:
- Phase 0: Introduce the harness engineering concept (the Guides x Sensors dichotomy)
- Phase 1: Implement Computational Guards (hooks like
check-suppression.sh/check-protected-files.sh) - Phase 6: Health-check measurement with 4 metrics (Task Resolution Rate / Code Churn Rate / Verification Tax / Defect Escape Rate)
- Phase 11: Path-scoping rules and token reduction (compress the always-loaded portion to 10 files / 722 lines)
- Phase 13: Carryover absorption + building out the Notification Sensor (the latest transitional)
I record each Phase's decisions as ADRs (Architecture Decision Records) — 16 of them — in ~/.claude/docs/adr/. An ADR is "the convention of recording an important design decision as one markdown file each," letting you trace "why I did it" later. Representative ADRs:
- ADR-0001: Make harness self-review a monthly / quarterly cron
- ADR-0004: The Phase evolution roadmap (Foundation 0-6 / Consolidation 7-9 / Next-Gen 10+)
- ADR-0011: Move Opus 4.7's
effortLevelfrom removing the env to a settings.json field - ADR-0013: Make Plan-then-Execute a norm as a Workflow Gate
The 10 capabilities of a harness introduced in why-harness-is-important.md correspond, in my environment, almost exactly to the Phase 0-13 addition roadmap. The breakdown of the 10 capabilities is context isolation / harness-enforced tool restrictions / lazy-loaded rules / hooks' deterministic execution / model routing. The rest are subagent parallelism / memory cross-session persistence / modular system prompt / skill preloading / the Auto Mode classifier. My felt sense from running Phases is that a harness is something "continuously stacking up Ratchets," not something "finished."
By the way, I cover the detailed background theory and norms of Phases more deeply in a separate article, harness-engineering, so if you are interested in the harness framework itself, see there.
First read just the one why-harness-is-important.md to internalize "the value of features." For the remaining 11, pick and read only 1-2 on "the theme you are currently struggling with." Trying to read them all takes 30+ minutes, so just the amount you need, when you need it.
Chapter 9: A selection roadmapwhat to choose at your level
From all the elements introduced so far, I present 4 kinds of roadmaps for choosing only what matches your level. Because completing one before moving on sticks better than running several halfway, first pick just one closest to your current position.
9.1 Beginner roadmapfirst, get Claude Code running
Assumes you just installed Claude Code, or are within your first week of use.
- Setup: Read tutorial/day0/README.md and install with the OS-specific steps (linux / mac / windows)
- First project: Follow tutorial/day1/README.md and experience your first code generation with Claude Code
- Tips intro: Read through Boris 13 Tips (03/Jan/26)
- Practice: Practice only the Tips'
Prompting/Planning/Specscategories (start from plan mode / draw out the spec with AskUserQuestion / write a spec)
At this stage, do not reach for subagents or hooks; concentrate on getting used to plain conversation and plan mode with Claude Code alone.
9.2 Intermediate roadmapcombine the basic features
Assumes you can use Claude Code, but growing your own .claude/ is yet to come.
- Understand concepts: Read through best-practice/claude-subagents.md + claude-commands.md + claude-skills.md in order
- Run the showcase: Clone orchestration-workflow.md and run
/weather-orchestrator - Apply Tips: Practice the
CLAUDE.md,Skills,Hookscategories (organize CLAUDE.md to 200 lines or fewer, make one skill of your own, set up auto-format in a PostToolUse hook) - Build your own: Make 1-2 slash commands on the theme of a task you do at least once a day in your work
At this stage, even one more file in your own .claude/commands/ changes your relationship with Claude Code.
9.3 Advanced roadmapdesign the harness
Assumes you already run your own .claude/ and are looking for the next improvement direction.
- Organize the reasoning: Reconfirm the harness's 10 capabilities in why-harness-is-important.md
- Read large workflows closely: Read the source of Superpowers (14 skills) and ECC (48 agents + 143 commands + 230 skills)
- Introduce cross-model: Try QA review with Codex in 2 terminals, referencing cross-model-workflow.md
- Parallelize: Try one implementation example of agent teams / git worktrees / scheduled tasks
- Keep observing: Continuously follow Boris's / Thariq's latest tips (collected in the README's
🔔 SUBSCRIBEsection)
For reference, my ~/.claude/ has completed Phase 13 (carryover absorption + building out the Notification Sensor) as of May 2026. I am currently working on Phase 14 (full XML expansion + introducing Six Sigma statistical methods + the Tree-of-Thoughts reasoning pattern). As written in Chapter 8, Phases are my own milestone units, and the evolution roadmap is recorded in ADR-0004.
My felt sense is that a harness is something "of the nature of stacking up a new Ratchet each quarter," not something that "is finished and enters stable operation." As long as Claude Code itself updates frequently, this "continuously updating the harness" mode is likely to continue for the time being.
The parallelization line (agent teams / worktree / scheduled tasks) is already introduced, but cross-model is not yet (for the reason written in Chapter 6). My current outlook is that full adoption would start from the router approach via claude-code-router.
9.4 If you adopt "just 3"for people short on time
How to choose when you do not have time to read this repo and want to adopt just the 3 most effective things.
- Always use Plan Mode (Tips - Planning/Specs category): Enter from plan mode for all complex tasks. Do not jump to implementation.
- Keep CLAUDE.md to 200 lines or fewer (Tips - CLAUDE.md category): When the project instruction document bloats, Claude starts ignoring it. Keep it concise.
- Make feature-specialized subagents (best-practice/claude-subagents.md): Avoid generic names like
general qaorbackend engineer. Make a subagent with a concrete name likepayment-flow-verifier, with a skill attached.
Even just these 3 change the stability of Claude Code's output.
Pick just one roadmap closest to your level and complete it before moving to the next level. Running them in parallel raises cognitive load and leaves everything halfway, so I recommend keeping to the order.
Chapter 10: Caveats and Open Questions
Finally, let me confirm the caveats for referencing this repo and the open questions the author poses to readers.
10.1 Five caveats: do not take it at face value
- The pace of updates: The repo is based on Claude Code v2.1.145 (released 2026-05-19). Because Anthropic's feature names and specs change frequently, when making important decisions, always reconfirm in the official docs.
- English assumed: The original Tips' sources (X tweets / YouTube / Reddit) are all in English. The in-repo explanations are also in English, so there will be scenes where you read while translating or alongside machine translation.
- It does not just run from copy-paste: Much of it is "implementation hints," and the content of
.claude/agents/<name>.mdmay not be written out. Adjustment to fit your own project is assumed. - The operation of an industry leader ≠ the optimal solution for a personal project: Adopting Anthropic's internal or Boris's personal workflow directly into a team often does not fit. The safe attitude is to extract only the reasoning of "why they do it this way" and translate it to your own situation.
- Mind the cost: Features like Cross-model workflow, Agent Teams parallel execution, Routines (cloud cron), and Computer Use greatly increase API credit consumption. Be sure to set a spending limit in the Anthropic Console.
10.2 Open Questions from the authorBillion-Dollar Questions
At the end of the README there is a Billion-Dollar Questions section, where the author lines up 13 unsolved problems he himself publishes as "I do not have answers either, but tell me if anyone has solved them." Let me introduce 3 representative categories.
Questions about Memory & Instructions (4):
- What to put in CLAUDE.md and what not to
- With a CLAUDE.md already in place, do you separately need a
constitution.mdorrules.md - How often should CLAUDE.md be updated, and how do you tell it has gone stale
- Why does Claude ignore CLAUDE.md instructions even when written MUST in all caps (reddit post: a case of 80% ignored)
Questions about Agents, Skills & Workflows (6):
- When to use command vs agent vs skill — and which cases are fine with just "vanilla Claude Code"
- Do agents / commands / workflows need updating with each model evolution
- Which is better, a generalist subagent or a feature/role-specialized subagent
- Use Claude Code's standard plan mode, or make your own plan command/agent that enforces the team's workflow
- How to coexist personal skills (e.g., your own
/implementwith your coding style) and community skills (e.g.,/simplify) - Will the era come where you convert an existing codebase to spec markdown -> delete the code -> have the AI regenerate from the spec and restore the same code as the original
Questions about Specs & Documentation (3):
- Does every feature need spec markdown
- How to maintain the update frequency of specs
- How to manage the ripple effect on other specs in new-feature implementation
These are not questions the author knows the "right answer" to; they are of the nature where readers find answers at their own sites. Keeping them as themes to explore after reading this article deepens your own operation.
While keeping the 5 caveats in mind, make adoption decisions on the Open Questions while thinking "how would I answer at my own site." Be especially conscious of caveat 3 (it does not run from copy-paste) and caveat 4 (an industry leader's operation does not necessarily fit you), and treat the repo as "material for thought," not "something to copy verbatim."
Chapter 11: Wrap-up and related links
shanraisshan/claude-code-best-practice is a curation collection that aggregates Claude Code's official features and community practices with primary-source links. In this article I surveyed the 13-directory structure, the catalog of 30+ concepts, the 12 development workflows, the 8 + 2 collections, the 3 cross-model approaches, the 83 Tips, and the 12 reports, and summarized a path for selection with 4 level-by-level roadmaps.
This repo is the kind of thing to keep on hand as a reference for growing your own .claude/, rather than "read and done." If a concept catches your eye, the way to use it is to jump straight from this article's links to the relevant file and read the original.
Related links
- Original repository: shanraisshan/claude-code-best-practice
- Author: Shayan Raisshan (GitHub)
- The author's other repositories:
- claude-code-hooks：a hook implementation collection (sound notifications / auto-format / blocking dangerous commands)
- claude-code-status-line：visualize context usage / cost
- codex-cli-best-practice：the Codex CLI version
- codex-cli-hooks：hooks for Codex CLI
- gemini-cli-best-practice：the Gemini CLI version
- gemini-cli-hooks：hooks for Gemini CLI
- ralph-wiggum-self-evolving-loop：the implementation of the Ralph Wiggum loop
- Anthropic official:
- Community subscriptions (excerpted from the README's
🔔 SUBSCRIBEsection):- Reddit: r/ClaudeAI, r/ClaudeCode, r/Anthropic
- X: Boris Cherny, Thariq, Cat Wu, Lydia Hallie
- YouTube: Anthropic, Lenny's Podcast, The Pragmatic Engineer
- Video explanations (the 3 main ones from the repo's
videos/directory):
Finally, this repository is continuously updated. The numbers introduced in this article (445 files / 83 Tips / 12 Workflows, etc.) are a snapshot as of May 25, 2026. Check the latest state in the original README.