Usage Guide & Workflows

This guide provides practical examples and best practices for using the Claude Code Development Kit in your day-to-day development.

Creating Your Project's Documentation Structure

After installing the kit, the first step is to document your existing project structure so the AI can understand it. The kit uses a system of CONTEXT.md files placed at different levels of your directory tree.

The setup script provides templates for these files:

docs/CONTEXT-tier2-component.md: Use this as a template for component-level documentation.
docs/CONTEXT-tier3-feature.md: Use this for more granular, feature-level documentation.

Here’s how you would structure it:

your-project/
├── CLAUDE.md                  # Master AI context (Tier 1)
├── backend/
│   ├── CONTEXT.md       # Backend context (Tier 2) - 🔴 create this
│   └── src/api/
│       └── CONTEXT.md   # API context (Tier 3) - 🔴 create this
└── frontend/
    ├── CONTEXT.md       # Frontend context (Tier 2) - 🔴 create this
    └── src/components/
        └── CONTEXT.md   # Components context (Tier 3) - 🔴 create this

To create these files, you can either copy the templates manually or use the /create-docs command:

/create-docs "backend/CONTEXT.md"

Typical Workflows

Here are some common development scenarios and how to use the kit's commands to handle them.

Workflow 1: Starting a New Feature

Gather Context: Before writing any code, ask the AI to analyze the project and formulate a plan.
```
/full-context "implement user authentication across backend and frontend"
```
The system will auto-load documentation, spawn specialized agents (security, backend, frontend), and consult MCP servers to provide a comprehensive analysis and implementation plan.
Implement the Feature: Work with Claude Code to implement the plan.
Review the Code: Once the implementation is done, ask for a multi-perspective review.
```
/code-review "review authentication implementation"
```
Update Documentation: Finally, update the project's documentation to reflect the new feature.
```
/update-docs "document authentication changes"
```
This keeps the AI's context current for future tasks.

Workflow 2: Refactoring a Large Module

Analyze the Module: Understand the current state of the code you want to refactor.
```
/full-context "analyze the old billing module at src/billing/legacy.js"
```
Perform the Refactor: Use the /refactor command to intelligently restructure the code.
```
/refactor "@src/billing/legacy.js into a new 'services' and 'utils' structure"
```
The command will map dependencies, create new files, and handle all import/export updates across the codebase.

Review and Update Docs: As before, finish by reviewing the changes and updating the documentation.

/code-review "review refactored billing module"
/update-docs "document new billing module structure"

Workflow 3: Solving a Complex Problem

When you're facing a difficult bug or a complex architectural decision, use /gemini-consult for an in-depth conversation.

Start the Consultation:
```
/gemini-consult "How can we optimize the real-time data pipeline for lower latency?"
```
This creates a persistent session with the Gemini Assistant MCP, automatically attaching your project context.
Iterate: Implement Gemini's suggestions and report back with the results in a follow-up prompt.
```
/gemini-consult
```
By providing no arguments, the command continues the existing session. You can describe the results of your implementation, and Gemini will provide further advice.
Document the Solution: Once the problem is solved, capture the key insights in your project's documentation.
```
/update-docs "document the new data pipeline optimization strategy"
```

Best Practices

Let Documentation Guide Development: The 3-tier structure is designed to mirror natural architectural boundaries. Use it to plan your components.
Update Documentation Immediately: Use /update-docs after any significant change to keep the AI's context from becoming stale.
Trust the Auto-Loading: Avoid manually feeding context to the AI. The commands and hooks are designed to handle this for you.
End Your Session with /handoff: To preserve context between work sessions, use the /handoff command. It saves your progress to docs/ai-context/handoff.md.
```
/handoff "Finished implementing the API endpoints for auth; frontend work is next."
```