160 lines
4.2 KiB
Markdown
160 lines
4.2 KiB
Markdown
# Claude Code Platform Architecture
|
|
|
|
This directory contains the core configuration and extensions that transform Claude Code from a coding assistant into a complete development platform.
|
|
|
|
## 📁 Directory Structure
|
|
|
|
```
|
|
.claude/
|
|
├── agents/ # AI agents that assist with various tasks
|
|
├── commands/ # Custom commands that extend Claude Code
|
|
├── tools/ # Shell scripts for automation and notifications
|
|
├── docs/ # Deep-dive documentation
|
|
├── settings.json # Claude Code configuration
|
|
└── README.md # This file
|
|
```
|
|
|
|
## 🏗️ Architecture Overview
|
|
|
|
### AI Agents
|
|
|
|
The `agents/` directory contains the AI agents that assist with various tasks within Claude Code.
|
|
|
|
- Each `.md` file defines a specific agent and its capabilities.
|
|
- The agents can be composed together to handle more complex tasks.
|
|
- Agents can also share data and context with each other.
|
|
|
|
### Custom Commands
|
|
|
|
The `commands/` directory contains markdown files that define custom workflows:
|
|
|
|
- Each `.md` file becomes a slash command in Claude Code
|
|
- Commands can orchestrate complex multi-step processes
|
|
- They encode best practices and methodologies
|
|
|
|
### Automation Tools
|
|
|
|
The `tools/` directory contains scripts that integrate with Claude Code:
|
|
|
|
- `notify.sh` - Cross-platform desktop notifications
|
|
- `make-check.sh` - Intelligent quality check runner
|
|
- `subagent-logger.py` - Logs interactions with sub-agents
|
|
- Triggered by hooks defined in `settings.json`
|
|
|
|
### Configuration
|
|
|
|
`settings.json` defines:
|
|
|
|
- **Hooks**: Automated actions after specific events
|
|
- **Permissions**: Allowed commands and operations
|
|
- **MCP Servers**: Extended capabilities
|
|
|
|
## 🔧 How It Works
|
|
|
|
### Event Flow
|
|
|
|
1. You make a code change in Claude Code
|
|
2. PostToolUse hook triggers `make-check.sh`
|
|
3. Quality checks run automatically
|
|
4. Notification hook triggers `notify.sh`
|
|
5. You get desktop notification of results
|
|
6. If sub-agents were used, `subagent-logger.py` logs their interactions to `.data/subagents-logs`
|
|
|
|
### Command Execution
|
|
|
|
1. You type `/command-name` in Claude Code
|
|
2. Claude reads the command definition
|
|
3. Executes the defined process
|
|
4. Can spawn sub-agents for complex tasks
|
|
5. Returns results in structured format
|
|
|
|
### Philosophy Integration
|
|
|
|
1. `/prime` command loads philosophy documents
|
|
2. These guide all subsequent AI interactions
|
|
3. Ensures consistent coding style and decisions
|
|
4. Philosophy becomes executable through commands
|
|
|
|
## 🚀 Extending the Platform
|
|
|
|
### Adding AI Agents
|
|
|
|
Options:
|
|
|
|
- [Preferred]: Create via Claude Code:
|
|
- Use the `/agents` command to define the agent's capabilities.
|
|
- Provide the definition for the agent's behavior and context.
|
|
- Let Claude Code perform its own optimization to improve the agent's performance.
|
|
- [Alternative]: Create manually:
|
|
- Define the agent in a new `.md` file within `agents/`.
|
|
- Include all necessary context and dependencies.
|
|
- Must follow the existing agent structure and guidelines.
|
|
|
|
### Adding New Commands
|
|
|
|
Create a new file in `commands/`:
|
|
|
|
```markdown
|
|
## Usage
|
|
|
|
`/your-command <args>`
|
|
|
|
## Context
|
|
|
|
- What this command does
|
|
- When to use it
|
|
|
|
## Process
|
|
|
|
1. Step one
|
|
2. Step two
|
|
3. Step three
|
|
|
|
## Output Format
|
|
|
|
- What the user sees
|
|
- How results are structured
|
|
```
|
|
|
|
### Adding Automation
|
|
|
|
Edit `settings.json`:
|
|
|
|
```json
|
|
{
|
|
"hooks": {
|
|
"YourEvent": [
|
|
{
|
|
"matcher": "pattern",
|
|
"hooks": [
|
|
{
|
|
"type": "command",
|
|
"command": "your-script.sh"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
### Adding Tools
|
|
|
|
1. Create script in `tools/`
|
|
2. Make it executable: `chmod +x tools/your-tool.sh`
|
|
3. Add to hooks or commands as needed
|
|
|
|
## 🎯 Design Principles
|
|
|
|
1. **Minimal Intrusion**: Stay in `.claude/` to not interfere with user's project
|
|
2. **Cross-Platform**: Everything works on Mac, Linux, Windows, WSL
|
|
3. **Fail Gracefully**: Scripts handle errors without breaking workflow
|
|
4. **User Control**: Easy to modify or disable any feature
|
|
5. **Team Friendly**: Configurations are shareable via Git
|
|
|
|
## 📚 Learn More
|
|
|
|
- [Command Reference](../.ai/docs/commands.md)
|
|
- [Automation Guide](../.ai/docs/automation.md)
|
|
- [Notifications Setup](../.ai/docs/notifications.md)
|