Skip to content

Commit 70d55ef

Browse files
ahmadhasan2k8ahmadhasan2k8
committed
Add setup script and documentation for Claude Code integration
- Add setup.sh script to easily configure dp:: commands - Create comprehensive SETUP.md with installation instructions - Add ARCHITECTURE.md explaining how dp commands work with Claude AI - Update README.md with clearer setup instructions - Add .claude/ to .gitignore (local setup directory) This makes it easy for users to set up the AI Architecture Advisor: 1. Clone the repo 2. Run ./setup.sh 3. Start using dp:: commands in Claude Code
1 parent 245b3d9 commit 70d55ef

File tree

5 files changed

+339
-7
lines changed

5 files changed

+339
-7
lines changed

‎.gitignore‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -159,4 +159,7 @@ notebooks/scratch/
159159

160160
# Docker
161161
.dockerignore
162-
docker-compose.override.yml
162+
docker-compose.override.yml
163+
164+
# Claude Code - local setup directory
165+
.claude/

‎README.md‎

Lines changed: 22 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -192,19 +192,35 @@ The AI uses advanced sequential thinking to:
192192
## 🚀 Installation & Setup
193193

194194
### Prerequisites
195-
- Python 3.11+
196-
- [Claude Code CLI](https://claude.ai/code)
195+
- Python 3.11+ (optional, for notebooks)
196+
- [Claude Code CLI](https://claude.ai/code) (required for dp:: commands)
197197

198-
### Setup
198+
### Quick Setup (2 minutes)
199199
```bash
200+
# Clone the repository
200201
git clone https://github.com/ahmadhasan2k8/ai-architecture-advisor.git
201202
cd ai-architecture-advisor
202203

203-
# Optional: Set up learning environment
204-
pip install -r learning-resources/requirements.txt
204+
# Run the setup script to enable dp:: commands
205+
./setup.sh
206+
207+
# Or manually copy commands
208+
mkdir -p .claude/commands
209+
cp commands/*.md .claude/commands/
210+
```
211+
212+
### Verify Installation
213+
```bash
214+
# Open Claude Code
215+
claude .
216+
217+
# Test a command
218+
/dp::analyze I need a payment processing system
205219
```
206220

207-
**That's it!** The AI commands work immediately through Claude Code.
221+
**That's it!** The dp:: commands are now available in Claude Code.
222+
223+
**→ [Detailed Setup Guide](SETUP.md)** for troubleshooting and manual setup.
208224

209225
## 📊 Capabilities
210226

‎SETUP.md‎

Lines changed: 197 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
1+
# AI Architecture Advisor - Setup Guide
2+
3+
## Overview
4+
5+
This guide explains how to properly set up the AI Architecture Advisor's design pattern commands (`dp::` commands) for use with Claude Code.
6+
7+
## Quick Setup (2 minutes)
8+
9+
```bash
10+
# 1. Clone the repository
11+
git clone https://github.com/ahmadhasan2k8/ai-architecture-advisor.git
12+
cd ai-architecture-advisor
13+
14+
# 2. Make dp commands available to Claude Code
15+
cp -r commands .claude/
16+
17+
# 3. Open Claude Code in the project directory
18+
claude .
19+
20+
# 4. Test that commands work
21+
# Try: /dp::analyze I need a system to handle multiple payment methods
22+
```
23+
24+
## How the dp Commands Work
25+
26+
### Command Structure
27+
The repository contains four design pattern commands in the `commands/` directory:
28+
- `analyze.md` - Comprehensive pattern analysis using sequential thinking
29+
- `check.md` - Quick pattern validation
30+
- `refactor.md` - Code analysis for pattern opportunities
31+
- `validate.md` - Anti-pattern detection
32+
33+
**Important**: These are instruction files for Claude AI, not executable scripts. They tell Claude how to analyze your code using AI reasoning.
34+
35+
### Claude Code Integration
36+
Claude Code automatically detects and loads commands from:
37+
- `.claude/commands/` directory in the project root
38+
- Each `.md` file becomes a callable command
39+
- Commands use the `/dp::` namespace
40+
41+
### How Analysis Works
42+
When you run a dp command:
43+
1. Claude reads the instructions from the command file
44+
2. Claude uses its AI capabilities to analyze your code/problem
45+
3. Claude applies the pattern knowledge embedded in the instructions
46+
4. You get AI-powered recommendations based on best practices
47+
48+
**Note**: The Python files in `ai-engine/` are separate analysis tools that can be run independently. The dp commands don't call these Python files - they work entirely through Claude's AI.
49+
50+
### Command Flow
51+
```
52+
Repository Structure → Claude Code Structure
53+
commands/ .claude/commands/
54+
├── analyze.md ├── analyze.md → /dp::analyze
55+
├── check.md ├── check.md → /dp::check
56+
├── refactor.md ├── refactor.md → /dp::refactor
57+
└── validate.md └── validate.md → /dp::validate
58+
```
59+
60+
## Manual Setup Steps
61+
62+
If the quick setup doesn't work, follow these steps:
63+
64+
### 1. Verify Prerequisites
65+
```bash
66+
# Check Claude Code is installed
67+
claude --version
68+
69+
# Should output version number
70+
# If not, install from: https://claude.ai/code
71+
```
72+
73+
### 2. Set Up Command Directory
74+
```bash
75+
# From the ai-architecture-advisor directory
76+
mkdir -p .claude/commands
77+
78+
# Copy the dp commands
79+
cp commands/*.md .claude/commands/
80+
```
81+
82+
### 3. Verify Setup
83+
```bash
84+
# List the commands
85+
ls -la .claude/commands/
86+
87+
# Should show:
88+
# analyze.md
89+
# check.md
90+
# refactor.md
91+
# validate.md
92+
```
93+
94+
### 4. Test Commands
95+
Open Claude Code in the project directory:
96+
```bash
97+
claude .
98+
```
99+
100+
Then test each command:
101+
```bash
102+
# Test analyze
103+
/dp::analyze I need to manage user sessions
104+
105+
# Test check
106+
/dp::check singleton for database connection
107+
108+
# Test refactor
109+
/dp::refactor src/main.py
110+
111+
# Test validate
112+
/dp::validate making all classes singleton
113+
```
114+
115+
## Troubleshooting
116+
117+
### "Command not found"
118+
1. Ensure you're in the project root directory
119+
2. Check `.claude/commands/` exists and contains the `.md` files
120+
3. Restart Claude Code
121+
122+
### "Commands not working properly"
123+
1. Verify the command files were copied correctly
124+
2. Check file permissions: `chmod 644 .claude/commands/*.md`
125+
3. Ensure no syntax errors in command files
126+
127+
### "Can't find .claude directory"
128+
The `.claude` directory might be hidden. Use:
129+
```bash
130+
ls -la | grep .claude
131+
```
132+
133+
## Command Reference
134+
135+
### `/dp::analyze <problem description>`
136+
Performs deep architectural analysis using sequential thinking AI to evaluate pattern options.
137+
138+
**Example:**
139+
```
140+
/dp::analyze Payment processing system with credit cards, PayPal, and crypto
141+
```
142+
143+
### `/dp::check <pattern> for <scenario>`
144+
Quick validation of whether a specific pattern fits your use case.
145+
146+
**Example:**
147+
```
148+
/dp::check strategy for handling 2 export formats
149+
```
150+
151+
### `/dp::refactor <file or directory>`
152+
Analyzes existing code to find pattern opportunities and anti-patterns.
153+
154+
**Example:**
155+
```
156+
/dp::refactor src/services/payment_handler.py
157+
```
158+
159+
### `/dp::validate <pattern usage description>`
160+
Checks for overengineering and pattern misuse.
161+
162+
**Example:**
163+
```
164+
/dp::validate using factory pattern for creating user objects
165+
```
166+
167+
## For Repository Maintainers
168+
169+
To ensure the commands work for all users:
170+
171+
1. Keep commands in the `commands/` directory as the source of truth
172+
2. Add `.claude/` to `.gitignore` (users create it locally)
173+
3. Document the setup process in README.md
174+
4. Consider adding a setup script:
175+
176+
```bash
177+
#!/bin/bash
178+
# setup.sh - Set up dp commands for Claude Code
179+
180+
echo "Setting up AI Architecture Advisor..."
181+
182+
# Create .claude directory structure
183+
mkdir -p .claude/commands
184+
185+
# Copy commands
186+
cp commands/*.md .claude/commands/
187+
188+
echo "✅ Setup complete! You can now use dp:: commands in Claude Code"
189+
echo "Try: /dp::analyze your architecture problem"
190+
```
191+
192+
## Next Steps
193+
194+
After setup, see:
195+
- [QUICK_START.md](QUICK_START.md) - Learn how to use the commands effectively
196+
- [dp_commands_guide.md](learning-resources/guides/dp_commands_guide.md) - Detailed command documentation
197+
- [README.md](README.md) - Project overview and capabilities

‎docs/ARCHITECTURE.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# AI Architecture Advisor - Architecture Documentation
2+
3+
## System Components
4+
5+
The AI Architecture Advisor consists of two main systems that work independently:
6+
7+
### 1. Claude Code Commands (`/dp::` commands)
8+
**Location**: `commands/` directory
9+
**Purpose**: Instructions for Claude AI to analyze design patterns
10+
**How it works**:
11+
- These are markdown files that tell Claude how to respond to dp commands
12+
- Claude uses its built-in tools (Read, Grep, etc.) to analyze code
13+
- No Python code is executed - it's all AI-driven analysis
14+
15+
### 2. Python Analysis Engine (Optional)
16+
**Location**: `ai-engine/` directory
17+
**Purpose**: Standalone Python tools for code analysis
18+
**Components**:
19+
- `pattern_knowledge.py` - Pattern decision criteria and thresholds
20+
- `code_analyzer.py` - AST-based Python code analysis
21+
- `repo_analyzer.py` - Repository-wide pattern detection
22+
- `refactoring_templates.py` - Code transformation templates
23+
24+
## How They Work Together (Or Don't)
25+
26+
**Important**: The dp commands and Python engine are **separate systems**:
27+
28+
1. **dp commands** work entirely through Claude AI:
29+
- You type `/dp::analyze <problem>`
30+
- Claude reads the instructions from `commands/analyze.md`
31+
- Claude analyzes using its AI capabilities and knowledge
32+
- No Python code is executed
33+
34+
2. **Python engine** is for standalone analysis:
35+
- Can be run separately: `python -m ai-engine.code_analyzer <file>`
36+
- Provides programmatic pattern detection
37+
- Not currently integrated with dp commands
38+
39+
## Why This Design?
40+
41+
- **Simplicity**: dp commands work immediately without Python setup
42+
- **Flexibility**: Claude can analyze any language, not just Python
43+
- **Power**: Claude's AI understanding goes beyond static analysis
44+
- **Optional complexity**: Python tools available for those who need them
45+
46+
## Future Integration Possibilities
47+
48+
The commands could potentially call the Python engine in the future:
49+
```python
50+
# Hypothetical future integration
51+
/dp::refactor file.py --use-python-engine
52+
```
53+
54+
But currently, they operate independently for maximum simplicity and compatibility.

‎setup.sh‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
#!/bin/bash
2+
# AI Architecture Advisor - Setup Script
3+
# Sets up dp:: commands for Claude Code
4+
5+
set -e # Exit on error
6+
7+
echo "🚀 Setting up AI Architecture Advisor for Claude Code..."
8+
echo
9+
10+
# Check if we're in the right directory
11+
if [ ! -f "README.md" ] || [ ! -d "commands" ]; then
12+
echo "❌ Error: Please run this script from the ai-architecture-advisor root directory"
13+
exit 1
14+
fi
15+
16+
# Check if Claude Code is installed
17+
if ! command -v claude &> /dev/null; then
18+
echo "⚠️ Warning: Claude Code CLI not found"
19+
echo " Please install from: https://claude.ai/code"
20+
echo " Continuing with setup anyway..."
21+
echo
22+
fi
23+
24+
# Create .claude/commands directory
25+
echo "📁 Creating .claude/commands directory..."
26+
mkdir -p .claude/commands
27+
28+
# Copy dp commands
29+
echo "📋 Copying dp commands..."
30+
cp -v commands/*.md .claude/commands/
31+
32+
# Verify setup
33+
echo
34+
echo "✅ Verifying setup..."
35+
if [ -f ".claude/commands/analyze.md" ] && \
36+
[ -f ".claude/commands/check.md" ] && \
37+
[ -f ".claude/commands/refactor.md" ] && \
38+
[ -f ".claude/commands/validate.md" ]; then
39+
echo "✅ All commands copied successfully!"
40+
else
41+
echo "❌ Error: Some commands may not have been copied"
42+
exit 1
43+
fi
44+
45+
# Success message
46+
echo
47+
echo "🎉 Setup complete!"
48+
echo
49+
echo "You can now use the dp:: commands in Claude Code:"
50+
echo " /dp::analyze - Deep pattern analysis with AI reasoning"
51+
echo " /dp::check - Quick pattern validation"
52+
echo " /dp::refactor - Find pattern opportunities in code"
53+
echo " /dp::validate - Detect anti-patterns and overengineering"
54+
echo
55+
echo "📖 Next steps:"
56+
echo " 1. Open Claude Code: claude ."
57+
echo " 2. Try: /dp::analyze I need a payment processing system"
58+
echo " 3. See QUICK_START.md for more examples"
59+
echo
60+
61+
# Make script executable for future runs
62+
chmod +x setup.sh 2>/dev/null || true

0 commit comments

Comments
 (0)