Improved flow
This commit is contained in:
Morten Olsen
285
docs/guides/ai-assistant.md
Normal file
285
docs/guides/ai-assistant.md
Normal file
@@ -0,0 +1,285 @@
|
||||
# AI Assistant Guide (opencode.nvim)
|
||||
|
||||
This guide covers using opencode.nvim for AI-assisted coding in Neovim.
|
||||
|
||||
## Overview
|
||||
|
||||
opencode.nvim provides AI assistance directly in Neovim:
|
||||
- Ask questions about code
|
||||
- Get explanations
|
||||
- Generate code and tests
|
||||
- Refactor and optimize
|
||||
- Review changes
|
||||
- Document code
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Open AI Panel
|
||||
|
||||
```
|
||||
<leader>kk Toggle opencode panel
|
||||
```
|
||||
|
||||
The panel opens on the right side (40% width).
|
||||
|
||||
### Ask a Question
|
||||
|
||||
```
|
||||
<leader>ka Ask opencode (prompts for input)
|
||||
```
|
||||
|
||||
Or with file context:
|
||||
```
|
||||
<leader>kA Ask about current file
|
||||
```
|
||||
|
||||
## Key Bindings
|
||||
|
||||
### General
|
||||
|
||||
| Key | Mode | Action |
|
||||
|-----|------|--------|
|
||||
| `<leader>kk` | n | Toggle opencode panel |
|
||||
| `<leader>ka` | n, v | Ask opencode |
|
||||
| `<leader>kA` | n, v | Ask about current file |
|
||||
| `<leader>kn` | n | New session |
|
||||
|
||||
### Code Understanding
|
||||
|
||||
| Key | Mode | Action |
|
||||
|-----|------|--------|
|
||||
| `<leader>ke` | n | Explain code near cursor |
|
||||
| `<leader>kE` | v | Explain selection |
|
||||
|
||||
### Code Review
|
||||
|
||||
| Key | Mode | Action |
|
||||
|-----|------|--------|
|
||||
| `<leader>kr` | n | Review current file |
|
||||
| `<leader>kg` | n | Review git diff |
|
||||
| `<leader>kf` | n | Fix diagnostics/errors |
|
||||
| `<leader>kq` | n | Fix quickfix items |
|
||||
|
||||
### Code Generation
|
||||
|
||||
| Key | Mode | Action |
|
||||
|-----|------|--------|
|
||||
| `<leader>ko` | v | Optimize selection |
|
||||
| `<leader>kR` | v | Refactor selection |
|
||||
| `<leader>kd` | v | Document selection |
|
||||
| `<leader>kt` | v | Generate tests for selection |
|
||||
|
||||
### Harpoon Integration
|
||||
|
||||
| Key | Mode | Action |
|
||||
|-----|------|--------|
|
||||
| `<leader>kh` | n | Ask about harpooned files |
|
||||
| `<leader>kH` | n | Analyze harpooned files |
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### Understanding Code
|
||||
|
||||
1. Place cursor on complex code
|
||||
2. `<leader>ke` - Explain code near cursor
|
||||
|
||||
Or for larger sections:
|
||||
1. Select code in visual mode (`V`)
|
||||
2. `<leader>kE` - Explain selection
|
||||
|
||||
### Fixing Bugs
|
||||
|
||||
1. See error in diagnostics
|
||||
2. `<leader>kf` - Ask AI to fix
|
||||
3. Review suggested fix
|
||||
4. Apply or modify as needed
|
||||
|
||||
### Generating Tests
|
||||
|
||||
1. Select function to test (`V` for lines)
|
||||
2. `<leader>kt` - Generate tests
|
||||
3. Review generated tests
|
||||
4. Adjust assertions as needed
|
||||
|
||||
### Refactoring
|
||||
|
||||
1. Select code to refactor (`V`)
|
||||
2. `<leader>kR` - Request refactoring
|
||||
3. Describe what you want (or let AI decide)
|
||||
4. Review and apply
|
||||
|
||||
### Code Review
|
||||
|
||||
Before committing:
|
||||
```
|
||||
<leader>kg Review git diff
|
||||
```
|
||||
|
||||
AI will analyze your changes and suggest improvements.
|
||||
|
||||
### Documenting Code
|
||||
|
||||
1. Select function/class (`V`)
|
||||
2. `<leader>kd` - Generate documentation
|
||||
3. Review generated docs
|
||||
4. Integrate into code
|
||||
|
||||
## Working with Multiple Files
|
||||
|
||||
### Harpoon Context
|
||||
|
||||
Mark related files with harpoon, then ask about them together:
|
||||
|
||||
1. Mark files: `<leader>H` on each file
|
||||
2. `<leader>kh` - Ask about all harpooned files
|
||||
3. AI has context of all marked files
|
||||
|
||||
Example question:
|
||||
> "How does the user service interact with the database layer?"
|
||||
|
||||
### Analyze Architecture
|
||||
|
||||
```
|
||||
<leader>kH Analyze harpooned files
|
||||
```
|
||||
|
||||
Good for understanding relationships between files.
|
||||
|
||||
## Effective Prompting
|
||||
|
||||
### Be Specific
|
||||
|
||||
Bad: "Fix this code"
|
||||
Good: "This function throws an error when the array is empty. Add a guard clause."
|
||||
|
||||
### Provide Context
|
||||
|
||||
Bad: "Add error handling"
|
||||
Good: "Add try-catch with proper error logging following our project's error handling pattern"
|
||||
|
||||
### Ask for Explanations
|
||||
|
||||
- "Explain why this regex works"
|
||||
- "What are the edge cases here?"
|
||||
- "Why might this be slow?"
|
||||
|
||||
### Request Alternatives
|
||||
|
||||
- "Show me 3 ways to implement this"
|
||||
- "What's a more functional approach?"
|
||||
- "How would you do this idiomatically in Go?"
|
||||
|
||||
## Session Management
|
||||
|
||||
### New Session
|
||||
|
||||
```
|
||||
<leader>kn Start fresh session
|
||||
```
|
||||
|
||||
Clears context for a new topic.
|
||||
|
||||
### Continuing Conversations
|
||||
|
||||
The panel maintains conversation history. Follow up naturally:
|
||||
1. Ask initial question
|
||||
2. "Can you also handle the null case?"
|
||||
3. "Now add tests for this"
|
||||
|
||||
## Integration with Workflow
|
||||
|
||||
### During Development
|
||||
|
||||
1. Write initial implementation
|
||||
2. `<leader>ke` - Understand any complex parts
|
||||
3. `<leader>kt` - Generate tests
|
||||
4. `<leader>ko` - Optimize if needed
|
||||
|
||||
### During Code Review
|
||||
|
||||
1. `<leader>gd` - Open diffview
|
||||
2. `<leader>kg` - AI review of changes
|
||||
3. Address suggestions
|
||||
4. Create PR
|
||||
|
||||
### While Debugging
|
||||
|
||||
1. Hit an error
|
||||
2. `<leader>kf` - Ask AI to fix
|
||||
3. Or `<leader>ke` - Understand the error first
|
||||
4. Apply fix
|
||||
|
||||
## Tips
|
||||
|
||||
### Quick Explanations
|
||||
|
||||
`K` (hover) shows LSP docs, but for deeper understanding:
|
||||
```
|
||||
<leader>ke AI explanation with context
|
||||
```
|
||||
|
||||
### Iterative Refinement
|
||||
|
||||
1. Get initial suggestion
|
||||
2. "Make it more concise"
|
||||
3. "Add error handling"
|
||||
4. "Use async/await instead"
|
||||
|
||||
### Learning Patterns
|
||||
|
||||
Ask AI to explain patterns:
|
||||
- "Explain the repository pattern used here"
|
||||
- "What design pattern would improve this?"
|
||||
- "Show me the idiomatic way in this language"
|
||||
|
||||
### Code Generation Templates
|
||||
|
||||
For repetitive tasks:
|
||||
1. `<leader>ka`
|
||||
2. "Generate a CRUD API endpoint for User model following the pattern in user.controller.ts"
|
||||
|
||||
## Customization
|
||||
|
||||
### Panel Position
|
||||
|
||||
Configured in `lua/plugins/opencode.lua`:
|
||||
```lua
|
||||
opts = {
|
||||
window = {
|
||||
position = "right", -- or "left", "top", "bottom"
|
||||
width = 0.4, -- 40% of screen
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Auto-reload
|
||||
|
||||
When AI edits files, they auto-reload:
|
||||
```lua
|
||||
auto_reload_buffers_on_edit = true,
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Panel Not Opening
|
||||
|
||||
1. Check opencode is installed: `:Lazy`
|
||||
2. Verify configuration in `lua/plugins/opencode.lua`
|
||||
|
||||
### Slow Responses
|
||||
|
||||
- Large files take longer
|
||||
- Consider selecting specific sections instead of whole files
|
||||
|
||||
### Context Issues
|
||||
|
||||
If AI seems confused:
|
||||
1. `<leader>kn` - New session
|
||||
2. Provide clearer context
|
||||
3. Select specific code rather than asking about whole file
|
||||
|
||||
### Not Understanding Codebase
|
||||
|
||||
Use harpoon to provide multi-file context:
|
||||
1. Mark relevant files
|
||||
2. `<leader>kh` - Include them in question
|
||||
Reference in New Issue
Block a user