Initial commit
This commit is contained in:
Zhongwei Li
344
skills/oracle/References/integration-guide.md
Normal file
344
skills/oracle/References/integration-guide.md
Normal file
@@ -0,0 +1,344 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user