Claude Code Insights

English | 繁體中文

The most comprehensive advanced Claude Code guide in the Chinese-speaking community — covering CLAUDE.md architecture, Skills authoring, Subagent orchestration, with ready-to-use practical examples.

Maintained by dianyike / 典億創研工作室. Freelance engineer specializing in web development, web scraping automation, and API integration. This repo is a distillation of my real-world experience using Claude Code in client projects.

Website · Threads · Contact

Who Is This For

You are...	Start here	What you'll get
New to Claude Code	CLAUDE.md Guide	Understand the three-layer architecture, Hooks, and how to avoid common anti-patterns
Experienced, looking to level up	Skills Guide → Subagent Guide	Hub-and-Spoke architecture, decision matrices, black-box problem solutions
Freelancer / Solo developer	Practical Examples: grill-me → write-prd → prd-to-plan → tdd	A complete workflow from design interrogation to TDD implementation

Contents

File	Description	Audience
claude-md-best-practices.md	CLAUDE.md Best Practices — why not to use /init, the three-layer architecture model, Hooks over directives, anti-patterns	Beginners
skills-best-practices.md	Skills Best Practices — file format, loading mechanics, content writing principles, advanced patterns, design templates	Advanced
subagent-best-practices.md	Subagent Best Practices — the black-box problem and solutions, result persistence, tool scoping strategies, architectural patterns	Advanced

The three guides cross-reference each other. Recommended reading order: CLAUDE.md → Skills → Subagent.

Practical Examples

Subagent Examples

Example	Description	Difficulty
examples/security-reviewer	Dual-verification security audit — read-only /security:review (Semgrep + Codex cross-validation, confidence scoring) + opt-in /security:fix (convergence-hardened Fix-Verify Loop with falsifiable predictions, tiered rollback, hypothesis ledger). Strict review/fix boundary: review is always read-only; fix requires explicit user opt-in and runs in main conversation. Implements Harness Engineering methodology	Advanced

Hook Examples

Example	Description	Difficulty
examples/npm-supply-chain-defense	npm supply chain three-layer defense — .npmrc script blocking + PreToolUse Hook checks (registry, OSV.dev, version resolution, CLI syntax validation) + Semgrep supply chain scanning. Includes 42 regression tests	Advanced

Rules Examples

Example	Description	Difficulty
examples/rules	Production-tested .claude/rules/ starter kit — 6 rule files + localization template. Features a pragmatism layer (risk-tier meta-rule that scopes enforcement), violation signals for self-detection, and a "Why" line on every rule so Claude follows intent, not just the letter. Ready to copy into any project.	Beginner

Skills Examples

The following Skills are adapted from mattpocock/skills, reworked with templates extracted to templates/, reference materials moved to reference/, and Gotchas sections added.

Example	Description	Use Case
examples/grill-me	Design Interrogation — traverses every branch of a decision tree, resolving design decision dependencies one by one	Pre-coding design stress test
examples/write-prd	Write PRD — turns design decisions or rough ideas into a structured requirements document, bridging grill-me and prd-to-plan	Requirements authoring and structuring
examples/tdd	TDD Workflow — red-green-refactor vertical slices with test examples, mock guidelines, and deep module design reference	Feature development and bug fixes
examples/prd-to-plan	PRD to Implementation Plan — breaks requirements into tracer bullet vertical slices, outputs to ./plans/, with optional Codex review for high-risk plans	Requirements decomposition and phase planning
examples/write-a-skill	Skill Builder Meta-Skill — content type decisions, invocation control, security configuration, Gotchas iteration loop. Includes eval workflow reference	Creating new Skills
examples/skill-eval-toolkit	Skill Eval Toolkit — eval-driven testing, quantitative benchmarking, blind A/B comparison, description trigger optimization, and SKILL.md body autopilot keep/revert loop	Validating and optimizing existing Skills

Solo Development Workflow: /grill-me (interrogate the design) → /write-prd (write the PRD) → /prd-to-plan (break into phases, optionally review with Codex) → /tdd (implement one by one)

Skill Development Workflow: /write-a-skill (author the skill) → /skill-eval-toolkit (evaluate and optimize)

write-prd — PRD Authoring Skill

Fills the gap between /grill-me and /prd-to-plan — turns design decisions or rough ideas into a structured PRD:

• One-question-per-turn structured interview (target user → success state → non-goals)
• Enforces P0/P1/P2 priority tiers, References citing decision records, docs/prds/ output convention
• Stays at product / system-contract level — n