Claude Code Best Practice: a living index for moving from improvising to working with agents

Everything you need to know about shanraisshan/claude-code-best-practice: a reference guide, examples, and workflows for using Claude Code’s primitives with more discipline.

What Claude Code Best Practice is

Claude Code Best Practice is a documentation repository curated by Shayan Rais (shanraisshan). Its stated goal is to move from “vibe coding” to agent engineering. It doesn’t ship a model, a server, or an installable plugin: it collects and connects documentation, versioned examples, and recommendations for Claude Code.

Its map covers subagents, commands, skills, hooks, MCP servers, configuration, memory, restore points, startup options, and workflows. The repository distinguishes three things: best-practice documentation, a local implementation under .claude/, and external sources. That’s why it works more as a course and pattern catalog than as a single prescriptive workflow.

Futuristic dark-mode diagram showing three separate, glowing layers: documented knowledge on top, connected orchestration gears in the middle, and implementation code blocks under .claude/ at the bottom.

The guide itself suggests not reading it as a skill you install and run. It recommends studying Claude Code’s primitives, running the /weather-orchestrator example, and reusing the command → agent → skill pattern to build your own workflow.

The origin: documenting a fast-moving set of tools

The repository was created on October 31, 2025. The first commit, from that same moment, is simply titled Initial commit. The GitHub account identifies its author as Shayan Rais, a software architect at disrupt.com, based in Karachi, Pakistan.

No independent, verifiable launch entry appeared during this investigation. The verifiable history is therefore limited to the repository’s creation and its public evolution. The README presents itself as a practical response to Claude Code’s continuous expansion: it maintains a feature table, a collection of tips attributed to official and community sources, local implementations, and a log of reports.

There’s a central tension in the project: Claude Code keeps gaining native capabilities, while the ecosystem produces external commands, skills, and frameworks. The repository doesn’t propose replacing what’s native. On the contrary, it links Anthropic’s official documentation alongside its own and third-party examples; for instance, it lists planning modes, agent teams, worktrees, scheduled tasks, reviews, and configuration. The guide tries to organize those pieces and make clear which mechanism is native and which is a practice or extension.

Visualization of a glowing core labeled Claude Code Native surrounded by orbital rings: the inner rings show native primitives like subagents, hooks, and memory, and the outer rings show community extensions and MCP servers.

Philosophy and principles

The verifiable philosophy can be summarized like this:

From conversation to agent engineering. The project’s subtitle frames a shift from improvisation toward a reproducible process.
Learn the primitives before copying recipes. The README asks readers to understand agents, commands, skills, and hooks before composing a workflow.
Separate knowledge, orchestration, and implementation. Practice documents are distinguished from the executable files under .claude/ and from an orchestration example.
Plan, execute, review, and deliver. The methodology table organizes its options around researching, planning, executing, reviewing, and publishing.
Preserve context and verify. Its tips highlight fresh sessions for new tasks, summaries before rolling back, subagents to isolate intermediate outputs, and review before merging changes.

Four neon icons arranged in a circular flow on a dark background, representing planning, executing, reviewing, and delivering: a holographic blueprint, a glowing play button, a magnifying glass over code, and an upload arrow.

These aren’t laws or experimental results from the repository. They’re a curation of recommendations whose origin is linked in every row. The README itself keeps open questions about memory, instructions, conflicts between skills, and outdated documentation; that avoids presenting agent discipline as a solved problem.

High-tech dark-mode illustration of a digital vault door securing a glowing stream of context, next to a holographic checklist with green neon checkmarks for reviewing before merging, and isolated subagents working in separate digital bubbles.

How it works

The content is organized into directories for practice, implementation, development workflows, reports, tutorials, videos, and a sample configuration. The demonstration pattern is:

Start Claude Code with claude.
Invoke /weather-orchestrator.
Let the command call an agent, which in turn uses a skill.

Cyberpunk dark-mode terminal showing the flow of the /weather-orchestrator example: a command block triggers an agent block, which in turn activates a skill block, connected by neon orange and green data lines.

That example expresses the composition the repository proposes: commands are reusable entry points, agents provide context or specialization, and skills encapsulate instructions and resources. The README places the formats at .claude/commands/<name>.md, .claude/agents/<name>.md, and .claude/skills/<name>/SKILL.md.

The catalog also documents ways of working that aren’t code from the repository: --worktree or -w for isolation, /code-review ultra and claude ultrareview [target] for review, /ultraplan for planning, and /loop or /schedule for repetitive tasks. It includes a cross-model methodology: planning in Claude Code and doing a quality review in Codex through two terminals, or using a plugin, MCP, or router depending on the case.

Two futuristic terminals side by side on a dark desk: one shows Claude Code in neon blue for planning, the other shows Codex CLI in neon green for quality review, connected by a holographic router.

The most concrete practical recommendation is turning a repeated process into a versioned command or skill. At the same time, the repository flags operational risks: avoid dangerous global permissions, prefer permission lists and isolation, and don’t let automated workflows replace testing, review, or observability.

Official and semi-official status

The project is community-run, not an Anthropic repository. The README doesn’t document a publication in the official Claude Code plugin marketplace. Its author is Shayan Rais, and the GitHub API doesn’t attribute it to Anthropic.

Its relationship with Anthropic is one of reference and compatibility: it repeatedly links Claude Code’s official documentation for features like subagents, skills, hooks, MCP, configuration, memory, reviews, and worktrees. It also includes links to official anthropics/skills resources and Claude Code documentation. That provides traceability for part of its claims, but it doesn’t amount to endorsement, certification, or vendor support.

In practice it can be considered a semi-official guide only in the informal sense that it catalogs official features and cites its sources. There’s no retrieved evidence of acceptance in an official marketplace, Anthropic sponsorship, or designation as a standard. The README shows commercial support from disrupt.com and ClaudeKit, which also shouldn’t be confused with Anthropic’s backing.

The ecosystem

Repositories by the same author

Shayan Rais’s account shows a small set of repositories that extend the same approach. The following figures come from the GitHub API queried on August 1, 2026:

shanraisshan/claude-code-hooks: Claude Code hook examples with sound; 491 stars and 48 forks.
shanraisshan/codex-cli-best-practice: an equivalent guide for Codex CLI; 949 stars and 64 forks.
shanraisshan/codex-cli-hooks: hooks for Codex CLI; 65 stars and 7 forks.
shanraisshan/gemini-cli-best-practice: an equivalent guide for Gemini CLI; 70 stars and 6 forks.
shanraisshan/gemini-cli-hooks: hooks for Gemini CLI; 9 stars and 2 forks.
shanraisshan/ralph-wiggum-self-evolving-loop: a loop that generates questions to stress-test models; 41 stars and 4 forks.
shanraisshan/claude-code-status-line: a status line with context usage, Git status, and model; 60 stars and 7 forks.
shanraisshan/draw-json-architecture-skill: a skill for explaining an architecture in an HTML viewer based on JSON; 7 stars and 1 fork.

The README directly links the first five as sibling repositories. Taken together, they suggest a strategy of adapting documentation and workflow examples to different agent interfaces, not of creating a single framework that abstracts them all.

Derivatives, ports, and community translations

The GitHub API counts 6,360 forks of the guide. Among the visible derivatives retrieved are:

quizD/claude-code-best-practice, a fork with 14 stars. Its author opened pull request #40 to translate the README into Simplified Chinese.
lhfer/claude-code-best-practice-zh, a fork and adaptation for Chinese-speaking developers, with 3 stars and 1 fork.
clxzl/claude-code-best-practice-cn, a community repository not marked as a fork in the search result, described as a Chinese edition of the best practices; 125 stars and 37 forks.
moekyawaung-graduate/claude-code-best-practice, a fork with 11 stars.
paullarionov/claude-code-best-practice, a fork with 10 stars.

There are also localization attempts inside the main repository. Issue #48 requests a multilingual strategy; its author, minsang-alt, explicitly asked for a Korean version. In the comments, yiyou-eyo offered a Chinese translation and JuanCalderon-17 a Spanish version. These are community proposals, not officially approved translations.

The README itself compares or links neighboring methodologies and collections. To avoid attributing unproven compatibility, this table only summarizes the position the README assigns them:

Project	Verifiable relationship to this guide
`obra/superpowers`	A skills-based methodology with brainstorming, worktrees, planning, test-driven development, review, and closing.
`affaan-m/everything-claude-code`	A library of agents, commands, and skills with steps for planning, testing, implementing, reviewing, verifying, remembering, and improving.
`github/spec-kit`	A spec-driven workflow, from constitution and specification through implementation, analysis, and checklists.
`Fission-AI/OpenSpec`	A workflow of exploring, proposing, applying, verifying, continuing, and archiving.
`open-gsd/gsd-core`	A continuation noted in a pull request to the guide, of the earlier Get Shit Done repository, which had been archived.
`openai/codex-plugin-cc`	An official OpenAI plugin the README lists for Codex reviews from within Claude Code.

Not all of these are direct substitutes. Claude Code Best Practice is primarily a reference guide and set of examples; Superpowers, Spec Kit, and OpenSpec are process proposals, while codex-plugin-cc is a tool-to-tool integration.

Repo numbers

Measured: August 1, 2026, GitHub API.

Metric	Value
Stars	63,854
Forks	6,360
Real subscribers	471
Commits	1,671
Open issues reported by the API	14
Primary language	HTML
License	MIT
Created	October 31, 2025
Last push	August 1, 2026
Latest release	No GitHub releases

Futuristic holographic dashboard showing glowing neon statistics: 63,854 stars and 6,360 forks, floating above a dark, reflective surface with the GitHub logo integrated.

The top contributors returned by the API were shanraisshan with 847 contributions, claude with 818, claude[bot] with 4, and shayangd and neutmute with 1 each. The 1,671-commit count comes from the final page indicated by the API’s pagination link. GitHub’s watchers_count field mirrors the stars; that’s why subscribers_count is reported here as the number of real subscribers. Likewise, open_issues_count can include open pull requests, so 14 doesn’t necessarily mean 14 issues without pull requests.

How the community received it

The direct evidence retrieved is mostly from GitHub; no dedicated Hacker News discussion of shanraisshan/claude-code-best-practice was found. Hacker News searches returned threads about Anthropic’s official guide with a similar name, not about this repository, and those aren’t used here as reception of this project.

In issue #48, minsang-alt calls the resource a “great resource” while requesting multilingual support. The thread has 5 comments. yiyou-eyo and JuanCalderon-17 respectively offered Chinese and Spanish translations; it’s a concrete signal of interest in extending the guide’s reach, though it doesn’t confirm they were accepted.
Pull request #33, by frdzy, raises a usability critique: the README is so extensive they didn’t know where to start. They proposed /_learn and a personalized-tour skill; the pull request has 2 comments. The author replied that they preferred to wait because they didn’t want to bloat the repository with more agents, commands, and skills, and because hundreds of repositories and thousands of skills already existed. It’s a real objection to turning an extensive guide into yet another unbounded collection.
Pull request #40, by quizD, proposes a Chinese README and has 2 comments. The maintainer asked what it had been translated with; afterward, DaiOwen asked for it to be improved. This is a concrete reservation about the quality of an automated or insufficiently reviewed translation, not a disqualification of the original content.
In pull request #46, dotandlinejp proposed a Japanese guide for design and non-programmers. shayangd asked how it had been created and whether it had been quality-checked. The thread has 1 comment; it reflects the need to validate derivative guides before integrating them.

The reasonable conclusion is strong adoption on GitHub and active localization work, but there’s no retrieved evidence of uniform external approval. Stars measure interest, not the effectiveness of the advice or the quality of each derivative.

Claude Code Best Practice versus other proposals

Proposal	Verifiable overlap	Verifiable difference
`obra/superpowers`	Both organize an agent’s work around planning, execution, and verification.	Superpowers packages a skills-based method; this repository defines itself as a reference and course, adding links and Claude Code examples.
`affaan-m/everything-claude-code`	Both cover Claude Code agents, commands, and skills.	This guide’s table presents Everything Claude Code as an extensive library of artifacts; Claude Code Best Practice prioritizes documentation, reports, and explained patterns.
`github/spec-kit`	Both connect specification, planning, and implementation.	Spec Kit is structured as a spec-driven workflow; this guide doesn’t impose its own sequence or generate a constitution.
`Fission-AI/OpenSpec`	Both include exploration and verification as stages.	OpenSpec has defined lifecycle commands; this repository catalogs native mechanisms and practices from multiple sources.
`shanraisshan/codex-cli-best-practice`	They share an author and the same shift-to-agent-engineering approach.	The second targets Codex CLI; the documented repository focuses on Claude Code and its `.claude/` paths.

Use cases and who this repository can help

Teams standardizing on Claude Code can use it as a decision map before adding automation to a repository: reviewing which primitives cover commands, subagents, skills, hooks, MCP, memory, and permissions, then carrying a repeated procedure into .claude/commands/, .claude/agents/, or .claude/skills/. The /weather-orchestrator example lets you study the command → agent → skill journey before designing your own composition; the references to worktrees, restore points, and reviews help fit it into an existing change cycle.

Technical leads, trainers, and authors of internal guides can use the curation to prepare an adoption path: starting from the linked official sources, comparing methodologies like Superpowers, Spec Kit, or OpenSpec, and documenting local decisions instead of copying a closed recipe. It’s also useful for turning a recurring pattern into a versioned skill or command, while keeping the permission lists, tests, and human review that the repository itself recommends.

Abstract dark-mode image showing the transition from chaotic neon lines and scattered code fragments on the left toward an organized, geometric digital architecture on the right, representing the shift from improvisation to agent engineering.

Resources

Repository: https://github.com/shanraisshan/claude-code-best-practice
Documentation and getting started: https://github.com/shanraisshan/claude-code-best-practice#how-to-use
Orchestration example: https://github.com/shanraisshan/claude-code-best-practice/blob/main/orchestration-workflow/orchestration-workflow.md
Official Claude Code sources: https://code.claude.com/docs/en/features-overview
Linked official skills: https://github.com/anthropics/skills/tree/main/skills
Sibling repositories: https://github.com/shanraisshan?tab=repositories
Community discussions: https://github.com/shanraisshan/claude-code-best-practice/issues/48, https://github.com/shanraisshan/claude-code-best-practice/pull/33, https://github.com/shanraisshan/claude-code-best-practice/pull/40, https://github.com/shanraisshan/claude-code-best-practice/pull/46
Community and channels suggested by the README: https://www.reddit.com/r/ClaudeCode/, https://www.youtube.com/@anthropic-ai, https://chat.whatsapp.com/BDUV2stIS0c7X5uY7RY6nS

Note: this article combines the README and commit history of shanraisshan/claude-code-best-practice, the GitHub API, the repository’s pull requests and issues, and Hacker News queries carried out on August 1, 2026. The figures change over time.