ref: up
This commit is contained in:
Duc Nguyen
121
CLAUDE.md
Normal file
121
CLAUDE.md
Normal file
@@ -0,0 +1,121 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Repository Overview
|
||||
|
||||
This is a **Claude Marketplace** repository — a plugin ecosystem for Claude Code. It contains:
|
||||
|
||||
- **Plugin Registry** (`.claude-plugin/marketplace.json`): Defines available plugins/skills
|
||||
- **Fission Python Skill** (`fission-python/`): Plugin providing tools for Fission serverless Python projects
|
||||
- **Example Projects** (`data/examples/`): Example Fission Python projects (py-eom-quota, py-eom-storage, py-ailbl-scheduler)
|
||||
- **Fission Python Template** (`fission-python/template/`): Default template used when creating new Fission Python projects
|
||||
|
||||
> **Note:** `.sdlc-agents/` is **not** part of this repo. It is bind-mounted into the devcontainer from `~/Workspaces/self/sdlc-agents/agents` on the host.
|
||||
|
||||
## Plugin System Architecture
|
||||
|
||||
Claude Code discovers plugins via `.claude-plugin/marketplace.json` at the repository root. Each plugin entry:
|
||||
- Has an `id`, `name`, `description`, `type` (`skill`), `path`, and `tools` array
|
||||
- Points to a directory containing the tool implementations (executable `.sh` scripts)
|
||||
|
||||
The `fission-python` plugin (`fission-python/.claude-plugin/plugin.json`) exposes three tools:
|
||||
- `create-project` — `create-project.sh`
|
||||
- `analyze-config` — `analyze-config.sh`
|
||||
- `update-docstring` — `update-docstring.sh`
|
||||
|
||||
Both `marketplace.json` (registry) and `plugin.json` (plugin definition) must be present for discovery to work.
|
||||
|
||||
## Working with the Fission Python Skill
|
||||
|
||||
```bash
|
||||
# Make scripts executable (required after fresh clone)
|
||||
chmod +x fission-python/*.sh
|
||||
|
||||
# Create a new Fission Python project
|
||||
./fission-python/create-project.sh <project-name> [destination]
|
||||
|
||||
# Analyze .fission configuration in an existing project
|
||||
./fission-python/analyze-config.sh <project-path> # requires jq
|
||||
|
||||
# View or update Fission config embedded in a function docstring
|
||||
./fission-python/update-docstring.sh <file.py> <function-name> --get
|
||||
./fission-python/update-docstring.sh <file.py> <function-name> --set '<json>'
|
||||
```
|
||||
|
||||
### Fission Configuration in Docstrings
|
||||
|
||||
Fission config is embedded between ` ```fission ` and ` ``` ` markers in Python function docstrings:
|
||||
|
||||
```python
|
||||
def main():
|
||||
"""
|
||||
```fission
|
||||
{
|
||||
"name": "function-name",
|
||||
"http_triggers": {
|
||||
"trigger-name": {"url": "/endpoint", "methods": ["GET"]}
|
||||
}
|
||||
}
|
||||
```
|
||||
"""
|
||||
```
|
||||
|
||||
The `update-docstring.sh` tool parses and updates these blocks.
|
||||
|
||||
### Updating the Project Template
|
||||
|
||||
The template lives in `fission-python/template/`. When `create-project.sh` runs, it copies this directory and performs string substitutions (e.g., replacing project name). The plugin locates the template relative to its own position, making it portable.
|
||||
|
||||
Key template areas to modify:
|
||||
- `src/` — default function structure and helpers
|
||||
- `.fission/deployment.json` — default environment/package/function config
|
||||
- `.gitea/workflows/` — CI/CD pipeline workflows
|
||||
- `requirements.txt` / `dev-requirements.txt` — dependencies
|
||||
|
||||
## Testing
|
||||
|
||||
No centralized test runner. Test skill scripts by running them directly with various arguments, verifying argument parsing, file operations, and JSON output. Example projects in `data/examples/` use pytest.
|
||||
|
||||
## Configuration
|
||||
|
||||
- `.claude/settings.json` — Claude Code settings (plans directory)
|
||||
- `.claude-plugin/marketplace.json` — Plugin registry
|
||||
- `fission-python/.claude-plugin/plugin.json` — Plugin definition
|
||||
|
||||
## Development Environment (Devcontainer)
|
||||
|
||||
The `.devcontainer/devcontainer.json` configures a VS Code dev container with:
|
||||
- `postStartCommand`: `.devcontainer/setup.sh`
|
||||
- Bind mount: `~/Workspaces/self/sdlc-agents/agents` → `.sdlc-agents/` (external SDLC system)
|
||||
|
||||
Environment variables set in devcontainer:
|
||||
|
||||
| Variable | Default | Purpose |
|
||||
|---|---|---|
|
||||
| `ANTHROPIC_API_KEY` | (empty) | API key |
|
||||
| `ANTHROPIC_BASE_URL` | `https://openrouter.ai/api` | API endpoint |
|
||||
| `ANTHROPIC_MODEL` | `stepfun/step-3.5-flash:free` | Default model |
|
||||
| `ANTHROPIC_SMALL_FAST_MODEL` | `nvidia/nemotron-3-super-120b-a12b:free` | Alternate model |
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- **Plugin tools must be executable**: Run `chmod +x fission-python/*.sh`
|
||||
- **jq dependency**: `analyze-config.sh` requires `jq` for JSON parsing
|
||||
- **sed portability**: Scripts use GNU sed — on macOS use `sed -i ''` instead of `sed -i`
|
||||
- **Template exclusions**: `create-project.sh` excludes `.git`, `__pycache__`, `*.pyc`, `.env` on copy
|
||||
- **SDLC agents**: Only available inside devcontainer (bind-mounted, not in this repo)
|
||||
|
||||
## AI Guidelines
|
||||
|
||||
### Planning Rule
|
||||
Before making code changes for non-trivial tasks:
|
||||
1. Use `EnterPlanMode` to create a detailed implementation plan
|
||||
2. Explore the codebase to understand existing patterns
|
||||
3. Present the plan for approval before implementing
|
||||
4. Use `TaskList` to track progress on multi-step tasks
|
||||
|
||||
### Agent Usage Rule
|
||||
Use agents for complex, multi-step, or parallelizable tasks:
|
||||
- Research/exploration → Explore agent
|
||||
- Implementation planning → Plan agent
|
||||
Reference in New Issue
Block a user