345 lines
8.1 KiB
Markdown
345 lines
8.1 KiB
Markdown
# Oracle Integration Guide
|
|
|
|
This guide explains how to integrate Oracle into your development workflow for maximum effectiveness.
|
|
|
|
## Integration Methods
|
|
|
|
### 1. claude.md Integration (Recommended)
|
|
|
|
The `claude.md` file is automatically loaded by Claude Code at session start. Integrating Oracle here ensures context is always available.
|
|
|
|
#### Setup
|
|
|
|
1. Create or open `claude.md` in your project root:
|
|
|
|
```bash
|
|
touch claude.md
|
|
```
|
|
|
|
2. Add Oracle context section:
|
|
|
|
```markdown
|
|
# Project Documentation
|
|
|
|
## Project Knowledge (Oracle)
|
|
|
|
<!-- ORACLE_CONTEXT_START -->
|
|
<!-- Auto-updated by Oracle - Do not edit manually -->
|
|
|
|
Run to update:
|
|
```bash
|
|
python .claude/skills/oracle/scripts/generate_context.py --output claude.md --update
|
|
```
|
|
|
|
<!-- ORACLE_CONTEXT_END -->
|
|
|
|
## Project Overview
|
|
|
|
[Your project description...]
|
|
```
|
|
|
|
3. Update Oracle context:
|
|
|
|
```bash
|
|
python .claude/skills/oracle/scripts/generate_context.py --output claude.md --update
|
|
```
|
|
|
|
4. (Optional) Add to your workflow to auto-update after sessions.
|
|
|
|
#### Auto-Update
|
|
|
|
Add to your session workflow:
|
|
|
|
```bash
|
|
# After recording a session
|
|
python .claude/skills/oracle/scripts/record_session.py --interactive
|
|
python .claude/skills/oracle/scripts/generate_context.py --output claude.md --update
|
|
```
|
|
|
|
### 2. Session Start Hooks
|
|
|
|
Load Oracle context automatically when Claude Code starts.
|
|
|
|
#### Setup
|
|
|
|
1. Create hooks directory:
|
|
|
|
```bash
|
|
mkdir -p .claude/hooks
|
|
```
|
|
|
|
2. Create session-start hook:
|
|
|
|
```bash
|
|
cat > .claude/hooks/session-start.sh << 'EOF'
|
|
#!/bin/bash
|
|
# Load Oracle context at session start
|
|
|
|
python .claude/skills/oracle/scripts/load_context.py
|
|
EOF
|
|
|
|
chmod +x .claude/hooks/session-start.sh
|
|
```
|
|
|
|
3. Claude Code will run this hook at session start.
|
|
|
|
### 3. Git Hooks Integration
|
|
|
|
Track commits in Oracle timeline automatically.
|
|
|
|
#### Setup
|
|
|
|
1. Create post-commit hook:
|
|
|
|
```bash
|
|
cat > .git/hooks/post-commit << 'EOF'
|
|
#!/bin/bash
|
|
# Record commit in Oracle timeline
|
|
|
|
python .claude/skills/oracle/scripts/record_commit.py
|
|
EOF
|
|
|
|
chmod +x .git/hooks/post-commit
|
|
```
|
|
|
|
2. Commits are now automatically tracked in `.oracle/timeline/project_timeline.md`.
|
|
|
|
### 4. CI/CD Integration
|
|
|
|
Update Oracle knowledge as part of your CI/CD pipeline.
|
|
|
|
#### Example: GitHub Actions
|
|
|
|
```yaml
|
|
name: Update Oracle
|
|
|
|
on:
|
|
push:
|
|
branches: [ main ]
|
|
|
|
jobs:
|
|
update-oracle:
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- uses: actions/checkout@v2
|
|
|
|
- name: Update Oracle Timeline
|
|
run: |
|
|
python .claude/skills/oracle/scripts/record_commit.py
|
|
|
|
- name: Update claude.md
|
|
run: |
|
|
python .claude/skills/oracle/scripts/generate_context.py --output claude.md --update
|
|
|
|
- name: Commit changes
|
|
run: |
|
|
git config --local user.email "oracle@bot"
|
|
git config --local user.name "Oracle Bot"
|
|
git add claude.md
|
|
git diff --quiet && git diff --staged --quiet || git commit -m "Update Oracle context [skip ci]"
|
|
git push
|
|
```
|
|
|
|
## Workflow Patterns
|
|
|
|
### Pattern 1: Active Learning
|
|
|
|
**For:** Projects where you're learning and making frequent corrections.
|
|
|
|
**Workflow:**
|
|
1. Work on tasks
|
|
2. When corrected, immediately record: `python .claude/skills/oracle/scripts/record_session.py --corrections "wrong->right"`
|
|
3. Context auto-updates for next session
|
|
4. Corrections are avoided in future
|
|
|
|
**Best for:** New projects, learning new technologies
|
|
|
|
### Pattern 2: Pattern Detection
|
|
|
|
**For:** Mature projects with established patterns.
|
|
|
|
**Workflow:**
|
|
1. Record sessions regularly
|
|
2. Weekly: Run pattern analysis `python .claude/skills/oracle/scripts/analyze_patterns.py --generate-scripts`
|
|
3. Review and customize generated scripts
|
|
4. Use scripts for repeated tasks
|
|
|
|
**Best for:** Established projects, teams with repeated workflows
|
|
|
|
### Pattern 3: Knowledge Sharing
|
|
|
|
**For:** Team projects where knowledge needs to be shared.
|
|
|
|
**Workflow:**
|
|
1. Each team member records sessions
|
|
2. Knowledge base synced via git
|
|
3. `claude.md` updated and committed
|
|
4. All team members benefit from shared learning
|
|
|
|
**Best for:** Team projects, open source projects
|
|
|
|
### Pattern 4: Documentation Sync
|
|
|
|
**For:** Projects where documentation must stay current.
|
|
|
|
**Workflow:**
|
|
1. Record sessions with learnings
|
|
2. Use Oracle with documentation skill/tool
|
|
3. Auto-generate documentation updates from learnings
|
|
4. Review and commit documentation
|
|
|
|
**Best for:** Projects requiring up-to-date docs
|
|
|
|
## Context Injection Strategies
|
|
|
|
### Strategy 1: Minimal Context (Default)
|
|
|
|
Load only critical and high-priority items.
|
|
|
|
```bash
|
|
python .claude/skills/oracle/scripts/generate_context.py --tier 1
|
|
```
|
|
|
|
**Pros:** Low token usage, fast loading
|
|
**Cons:** May miss relevant context
|
|
**Use when:** Token budget is tight
|
|
|
|
### Strategy 2: Relevant Context
|
|
|
|
Load context relevant to current task.
|
|
|
|
```bash
|
|
python .claude/skills/oracle/scripts/generate_context.py --task "implement authentication"
|
|
```
|
|
|
|
**Pros:** Highly relevant, moderate token usage
|
|
**Cons:** Requires knowing the task upfront
|
|
**Use when:** Starting a specific task
|
|
|
|
### Strategy 3: Full Context
|
|
|
|
Load all available knowledge.
|
|
|
|
```bash
|
|
python .claude/skills/oracle/scripts/generate_context.py --tier 3
|
|
```
|
|
|
|
**Pros:** Complete picture, no missing context
|
|
**Cons:** High token usage, may be overwhelming
|
|
**Use when:** Complex tasks, architecture decisions
|
|
|
|
## Maintenance
|
|
|
|
### Weekly Maintenance
|
|
|
|
```bash
|
|
# 1. Analyze patterns
|
|
python .claude/skills/oracle/scripts/analyze_patterns.py
|
|
|
|
# 2. Generate automation scripts
|
|
python .claude/skills/oracle/scripts/analyze_patterns.py --generate-scripts
|
|
|
|
# 3. Update claude.md
|
|
python .claude/skills/oracle/scripts/generate_context.py --output claude.md --update
|
|
|
|
# 4. Review knowledge base
|
|
python .claude/skills/oracle/scripts/query_knowledge.py --summary
|
|
```
|
|
|
|
### Monthly Maintenance
|
|
|
|
1. Review corrections - are patterns emerging?
|
|
2. Update knowledge priorities
|
|
3. Archive old sessions (optional)
|
|
4. Review automation scripts - are they being used?
|
|
5. Clean up duplicate knowledge entries
|
|
|
|
### Knowledge Curation
|
|
|
|
Periodically review and curate:
|
|
|
|
```bash
|
|
# Find rarely used knowledge
|
|
python .claude/skills/oracle/scripts/query_knowledge.py --sort used
|
|
|
|
# Find old corrections (may be outdated)
|
|
python .claude/skills/oracle/scripts/query_knowledge.py --category corrections --sort recent
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Oracle Not Loading
|
|
|
|
**Problem:** Context not appearing at session start.
|
|
|
|
**Solutions:**
|
|
1. Check `.claude/hooks/session-start.sh` exists and is executable
|
|
2. Verify Oracle is initialized: `ls -la .oracle/`
|
|
3. Test manually: `python .claude/skills/oracle/scripts/load_context.py --verbose`
|
|
|
|
### Context Too Large
|
|
|
|
**Problem:** Too much context being injected.
|
|
|
|
**Solutions:**
|
|
1. Use tier 1 context: `--tier 1`
|
|
2. Increase priorities of only critical items
|
|
3. Use task-specific context instead of session-start
|
|
4. Review and archive old knowledge
|
|
|
|
### Knowledge Not Relevant
|
|
|
|
**Problem:** Loaded knowledge doesn't apply to current task.
|
|
|
|
**Solutions:**
|
|
1. Use task-specific context generation
|
|
2. Improve tags on knowledge entries
|
|
3. Use more specific queries
|
|
4. Update priorities to better reflect importance
|
|
|
|
### Scripts Not Generating
|
|
|
|
**Problem:** Pattern analysis doesn't find automation candidates.
|
|
|
|
**Solutions:**
|
|
1. Lower threshold: `--threshold 2`
|
|
2. Record more sessions
|
|
3. Be consistent in activity descriptions
|
|
4. Manually identify patterns and add as automation opportunities
|
|
|
|
## Best Practices
|
|
|
|
### 1. Record Sessions Consistently
|
|
|
|
Don't wait until end of day - record immediately after completing work while details are fresh.
|
|
|
|
### 2. Be Specific in Corrections
|
|
|
|
Instead of: "That's wrong"
|
|
Use: "Don't use innerHTML for user input -> use textContent to prevent XSS"
|
|
|
|
### 3. Tag Thoughtfully
|
|
|
|
Use consistent, meaningful tags. Review existing tags before creating new ones.
|
|
|
|
### 4. Prioritize Ruthlessly
|
|
|
|
Not everything is critical. Save high/critical priorities for things that truly matter.
|
|
|
|
### 5. Review Regularly
|
|
|
|
Knowledge bases become stale. Review and update monthly.
|
|
|
|
### 6. Use Automation
|
|
|
|
If pattern analysis suggests automation, implement it. Oracle works best when reducing repetitive LLM usage.
|
|
|
|
### 7. Share Knowledge
|
|
|
|
In team settings, commit Oracle knowledge to git (exclude sensitive session logs via .gitignore).
|
|
|
|
---
|
|
|
|
**Integration Version**: 1.0
|
|
**Last Updated**: 2025-11-19
|