Claude Code Practical Development Toolkit: Building a Flat, Pragmatic AI-Assisted Workflow

This article introduces the open-source project pragmatic-dev-toolkit, a plugin system designed for Claude Code. Through slash commands, automated review agents, and hook mechanisms, it helps teams establish pragmatic, lightweight development processes and avoid over-engineering. The core is integrating the YAGNI principle into AI-assisted development practices, covering the entire workflow from requirement clarification, code review, to test generation.

With the popularity of AI tools like Claude Code and GitHub Copilot, developers have gained intelligent partners. However, without clear workflow guidance, AI may accelerate the accumulation of technical debt. pragmatic-dev-toolkit aims to solve this problem—it is not a collection of code snippets but a complete workflow framework that integrates the YAGNI (You Aren't Gonna Need It) principle into daily practices.

The toolkit provides 8 core slash commands covering all development stages:

• /triage: Requirement clarification and decision entry point, aligning intentions and identifying information gaps;
• /next: Session navigator, recommending high-priority candidate tasks;
• /new-adr: Generate Architecture Decision Records (ADR);
• /run-plan: Execute plans, with automatic micro-commits and chunked reviews;
• /debug: Scientific debugging assistant, outputting diagnostic reports;
• /gen-tests: Generate test code compatible with the tech stack (supports Python pytest);
• /release: Version release coordinator, updating version numbers, generating change logs, etc.

The toolkit is configured with 5 automatic review agents:

1. Code Reviewer (YAGNI Reviewer): Identifies over-design (premature abstraction, redundant comments, etc.);
2. QA Reviewer: Checks the rationality of test coverage (main flow, boundary cases, etc.);
3. Security Reviewer: Scans for security risks (hard-coded credentials, missing input validation, etc.);
4. Doc Reviewer: Ensures documentation is in sync with code (missing identifiers, broken references, etc.);
5. Design Reviewer: Pre-reviews architecture decisions (rationality, comparison of alternative solutions, etc.).

Two automatically triggered hooks:

• block_env: PreToolUse hook that prevents direct editing of .env files, only allowing modifications to .env.example to avoid submitting sensitive configurations;
• run_pytest_python: PostToolUse hook that automatically runs pytest when Python file modifications are detected, outputting results only if tests fail.

Core philosophy: Bounded contexts and a unified language are necessary, but tactical-level formalism (such as mandatory layering) is not. It advocates YAGNI first, role-driven, and configurability. Relationship with scaffold-kit: A sister project (Copier-based template generator that produces project structures aligned with default paths), but the two are decoupled and can be used independently, embodying the Unix philosophy.

Typical development process:

1. Discover high-priority tasks (e.g., user authentication module) via /next;
2. Clarify requirements with /triage and decide to write an ADR;
3. Create an ADR explaining JWT selection using /new-adr;
4. Execute the plan with /run-plan, and review agents automatically check for YAGNI violations;
5. The block_env hook ensures no sensitive information is leaked before submission;
6. Coordinate version release with /release.

pragmatic-dev-toolkit represents a new paradigm for AI-assisted development: guiding AI to produce high-quality results through structured workflows, rather than generating code without restraint. The value of the tool lies in aligning with the real needs of the team. Recommendation: Teams that want to maintain code quality and avoid over-engineering in the AI era can refer to this project.