Analyze code architecture without modifying anything. This example shows how to use --skip for automation while keeping the analysis read-only.
The Script
#!/usr/bin/env -S ai --sonnet --skip
Summarize the architecture of this codebase. List the main entry points,
key modules, and how data flows through the system.
From examples/analyze-code.md. Uses Sonnet for better code understanding.
How It Works
Model Selection: Sonnet
Sonnet is the balanced model tier:
- Better than Haiku for code understanding and technical analysis
- Cheaper than Opus - you don’t need the most capable model for analysis
- Fast enough for real-time exploration
When to use each model:
| Task | Model | Why |
|---|
| Greet user, format text | --haiku | Simple text generation |
| Analyze code, run tests | --sonnet | Balanced reasoning + cost |
| Design architecture, complex debugging | --opus | Maximum reasoning power |
The --skip Flag
This is shorthand for --dangerously-skip-permissions. It allows the AI to:
- Read files without prompting you for each one
- Use tools automatically
- Explore the codebase freely
Wait, isn’t --skip dangerous?Yes, but only for write operations. This script’s prompt is read-only - it only asks for analysis. The AI won’t modify files unless your prompt tells it to.For true safety, use granular permissions:#!/usr/bin/env -S ai --sonnet --allowedTools 'Read' 'Grep' 'Glob'
Summarize the architecture of this codebase.
The Prompt
Summarize the architecture of this codebase. List the main entry points,
key modules, and how data flows through the system.
- Main entry points - where execution starts
- Key modules - important components
- Data flow - how information moves through the system
The more specific your prompt, the better the analysis.
Running the Script
Analyze any codebase
# Make it executable
chmod +x analyze-code.md
# Run in any project directory
cd ~/projects/my-app
./analyze-code.md
- Explore the directory structure
- Read key files (package.json, main entry points, etc.)
- Analyze the architecture
- Summarize findings
Override the provider
# Use AWS Bedrock instead
ai --aws analyze-code.md
# Use Opus for deeper analysis
ai --opus analyze-code.md
# Use local Ollama (free!)
ai --ollama analyze-code.md
Save output to file
./analyze-code.md > architecture-summary.txt
Real-World Usage
Quick Project Overview
When joining a new codebase:
cd ~/projects/new-repo
./analyze-code.md > ARCHITECTURE.md
Compare Multiple Projects
for dir in project-*; do
cd "$dir"
echo "# $dir" >> ../analysis.txt
../analyze-code.md >> ../analysis.txt
cd ..
done
CI/CD Documentation
Generate architecture docs automatically:
# .github/workflows/docs.yml
name: Update Architecture Docs
on:
push:
branches: [main]
jobs:
analyze:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Analyze codebase
run: |
curl -fsSL https://claude.ai/install.sh | bash
git clone https://github.com/andisearch/airun.git
cd airun && ./setup.sh
cd ..
ai --apikey --sonnet --skip << 'EOF' > ARCHITECTURE.md
Summarize this codebase architecture. List main entry points,
key modules, and data flow.
EOF
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
- name: Commit changes
run: |
git config user.name "Architecture Bot"
git config user.email "bot@example.com"
git add ARCHITECTURE.md
git commit -m "docs: update architecture" || true
git push
Customizing the Analysis
Focus on Specific Aspects
Security analysis:
#!/usr/bin/env -S ai --sonnet --skip
Analyze this codebase for security issues. Check for:
- SQL injection vulnerabilities
- XSS vulnerabilities
- Authentication/authorization flaws
- Sensitive data exposure
Be specific about file paths and line numbers.
#!/usr/bin/env -S ai --sonnet --skip
Analyze this codebase for performance issues:
- Inefficient algorithms (O(n²) or worse)
- Unnecessary re-renders
- Memory leaks
- Large bundle size contributors
#!/usr/bin/env -S ai --sonnet --skip
Analyze test coverage in this codebase:
- Which modules have tests?
- Which critical paths are untested?
- Are there obsolete tests?
- Suggest priority areas for new tests.
Limit Scope
#!/usr/bin/env -S ai --sonnet --skip
Analyze only the API layer in src/api/. Document:
- Available endpoints
- Request/response schemas
- Authentication requirements
Why --skip Works Here
This script uses --skip even though it’s read-only because:
- Automation - No permission prompts when reading files
- Speed - The AI explores freely without asking
- Safe prompt - The prompt never asks to modify anything
The risk comes from the prompt, not the flag. A read-only prompt with --skip is safe.
For production scripts, prefer explicit tool allowlists:--allowedTools 'Read' 'Grep' 'Glob'
Next Steps