Add AGENTS.md development guide for AI coding agents
- Document build/lint/test commands for Neovim config - Define code style guidelines based on .stylua.toml and existing patterns - Outline project conventions and development workflow - Include Neovim-specific considerations for plugin development
This commit is contained in:
Juanito
parent
f0584e2103
commit
f640f80e12
|
|
@ -0,0 +1,244 @@
|
||||||
|
# AGENTS.md - Development Guide for AI Coding Agents
|
||||||
|
|
||||||
|
This file provides essential information for AI coding agents working in this Neovim configuration repository. It covers build/lint/test commands, code style guidelines, and project conventions to ensure consistent development.
|
||||||
|
|
||||||
|
## Build/Lint/Test Commands
|
||||||
|
|
||||||
|
### Linting
|
||||||
|
- **Command**: `:lua require('lint').try_lint()`
|
||||||
|
- **Description**: Run linting on current buffer using nvim-lint plugin
|
||||||
|
- **File types**: Currently configured for markdown files with `markdownlint`
|
||||||
|
- **Manual command**: `markdownlint-cli file.md` (if available globally)
|
||||||
|
|
||||||
|
### Formatting
|
||||||
|
- **Command**: `:lua require('conform').format({ async = true, lsp_format = 'fallback' })`
|
||||||
|
- **Keybinding**: `<leader>f` (normal/visual mode)
|
||||||
|
- **Description**: Format current buffer using conform.nvim
|
||||||
|
- **Formatters by filetype**:
|
||||||
|
- Lua: `stylua`
|
||||||
|
- Python: `isort`, `black`
|
||||||
|
- JavaScript: `prettierd`, `prettier`
|
||||||
|
- Go: `gofmt`
|
||||||
|
- Rust: `rustfmt`
|
||||||
|
- YAML: `yamlfix`
|
||||||
|
- TOML: `taplo`
|
||||||
|
- Terraform: `terraform_fmt`
|
||||||
|
- Markdown: `markdownlint`
|
||||||
|
|
||||||
|
### Testing
|
||||||
|
- **Status**: No automated testing framework configured
|
||||||
|
- **Reason**: This is a Neovim configuration repository, not an application with unit tests
|
||||||
|
- **Manual testing**: `:checkhealth` for Neovim health checks, `:Lazy` for plugin status
|
||||||
|
|
||||||
|
### Single Test Execution
|
||||||
|
- **N/A**: No test suite exists for this configuration repository
|
||||||
|
|
||||||
|
### Health Checks
|
||||||
|
- **Command**: `:checkhealth`
|
||||||
|
- **Description**: Comprehensive Neovim health check including plugins and configuration
|
||||||
|
|
||||||
|
## Code Style Guidelines
|
||||||
|
|
||||||
|
### Formatting (.stylua.toml)
|
||||||
|
- **Column width**: 160 characters
|
||||||
|
- **Indent type**: Spaces
|
||||||
|
- **Indent width**: 2 spaces
|
||||||
|
- **Quote style**: Auto-prefer single quotes
|
||||||
|
- **Call parentheses**: None (omit when possible)
|
||||||
|
- **Simple statements**: Always collapse
|
||||||
|
|
||||||
|
### Imports
|
||||||
|
```lua
|
||||||
|
-- Standard require pattern
|
||||||
|
local module = require('module.name')
|
||||||
|
|
||||||
|
-- For plugins and external libraries
|
||||||
|
local telescope = require('telescope')
|
||||||
|
local conform = require('conform')
|
||||||
|
|
||||||
|
-- Conditional requires with error handling
|
||||||
|
local ok, plugin = pcall(require, 'optional.plugin')
|
||||||
|
if not ok then
|
||||||
|
-- Handle missing plugin gracefully
|
||||||
|
end
|
||||||
|
```
|
||||||
|
|
||||||
|
### Naming Conventions
|
||||||
|
- **Variables**: `camelCase` (e.g., `local bufferNumber = 1`)
|
||||||
|
- **Functions**: `camelCase` (e.g., `function setupLsp() end`)
|
||||||
|
- **Constants**: `UPPER_SNAKE_CASE` (e.g., `local MAX_RETRIES = 3`)
|
||||||
|
- **Modules**: `snake_case` for file names (e.g., `lsp_config.lua`)
|
||||||
|
- **Descriptive names**: Prefer clarity over brevity (e.g., `diagnosticConfig` over `diagCfg`)
|
||||||
|
|
||||||
|
### Error Handling
|
||||||
|
```lua
|
||||||
|
-- Safe plugin loading
|
||||||
|
local ok, result = pcall(require, 'plugin.name')
|
||||||
|
if not ok then
|
||||||
|
vim.notify('Plugin failed to load: ' .. result, vim.log.levels.WARN)
|
||||||
|
return
|
||||||
|
end
|
||||||
|
|
||||||
|
-- Safe function calls
|
||||||
|
local success, err = pcall(function()
|
||||||
|
-- Potentially failing operation
|
||||||
|
end)
|
||||||
|
if not success then
|
||||||
|
vim.notify('Operation failed: ' .. err, vim.log.levels.ERROR)
|
||||||
|
end
|
||||||
|
```
|
||||||
|
|
||||||
|
### Comments
|
||||||
|
```lua
|
||||||
|
-- Single line comments for explanations
|
||||||
|
-- Use for Neovim-specific behavior or complex logic
|
||||||
|
|
||||||
|
-- TODO: Future improvements
|
||||||
|
-- FIXME: Known issues
|
||||||
|
-- NOTE: Important information for maintainers
|
||||||
|
|
||||||
|
-- EmmyLua type annotations (when used)
|
||||||
|
---@param buffer number: The buffer number
|
||||||
|
---@return boolean: Success status
|
||||||
|
function processBuffer(buffer)
|
||||||
|
-- Implementation
|
||||||
|
end
|
||||||
|
```
|
||||||
|
|
||||||
|
### Function Organization
|
||||||
|
```lua
|
||||||
|
-- Anonymous functions for keymaps
|
||||||
|
vim.keymap.set('n', '<leader>key', function()
|
||||||
|
-- Implementation
|
||||||
|
end, { desc = 'Description of what this does' })
|
||||||
|
|
||||||
|
-- Named functions for complex logic
|
||||||
|
local function setupPlugin()
|
||||||
|
-- Setup code here
|
||||||
|
end
|
||||||
|
|
||||||
|
-- Call setup functions
|
||||||
|
setupPlugin()
|
||||||
|
```
|
||||||
|
|
||||||
|
### Table/Configuration Style
|
||||||
|
```lua
|
||||||
|
-- Consistent indentation and alignment
|
||||||
|
local config = {
|
||||||
|
option1 = true,
|
||||||
|
option2 = 'value',
|
||||||
|
nested = {
|
||||||
|
setting = 42,
|
||||||
|
enabled = false,
|
||||||
|
},
|
||||||
|
-- Align values when it improves readability
|
||||||
|
timeout_ms = 500,
|
||||||
|
max_retries = 3,
|
||||||
|
}
|
||||||
|
|
||||||
|
-- Plugin configurations follow this pattern
|
||||||
|
return {
|
||||||
|
'plugin/name',
|
||||||
|
opts = {
|
||||||
|
-- Options here
|
||||||
|
},
|
||||||
|
config = function()
|
||||||
|
-- Setup code
|
||||||
|
end,
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Autocommands
|
||||||
|
```lua
|
||||||
|
-- Use descriptive augroup names
|
||||||
|
local augroup = vim.api.nvim_create_augroup('plugin-name-feature', { clear = true })
|
||||||
|
|
||||||
|
vim.api.nvim_create_autocmd('FileType', {
|
||||||
|
group = augroup,
|
||||||
|
pattern = 'lua',
|
||||||
|
callback = function()
|
||||||
|
-- Callback implementation
|
||||||
|
end,
|
||||||
|
})
|
||||||
|
```
|
||||||
|
|
||||||
|
### Keymaps
|
||||||
|
```lua
|
||||||
|
-- Always include descriptions for discoverability
|
||||||
|
vim.keymap.set('n', '<leader>sh', builtin.help_tags, {
|
||||||
|
desc = '[S]earch [H]elp'
|
||||||
|
})
|
||||||
|
|
||||||
|
-- Use leader key consistently (<space>)
|
||||||
|
-- Group related mappings under leader prefixes
|
||||||
|
-- Follow existing patterns: s=search, t=toggle, h=git hunk, etc.
|
||||||
|
```
|
||||||
|
|
||||||
|
## Project Conventions
|
||||||
|
|
||||||
|
### File Organization
|
||||||
|
```
|
||||||
|
lua/
|
||||||
|
├── options.lua # Vim options and settings
|
||||||
|
├── keymaps.lua # Keybindings
|
||||||
|
├── autocommands.lua # Autocommands
|
||||||
|
├── lazy-config.lua # Lazy plugin manager setup
|
||||||
|
├── plugins_config/ # Plugin-specific configurations
|
||||||
|
│ ├── lsp.lua # LSP setup
|
||||||
|
│ ├── conform.lua # Formatting setup
|
||||||
|
│ ├── telescope.lua # Fuzzy finder setup
|
||||||
|
│ └── ...
|
||||||
|
└── custom/ # User customizations
|
||||||
|
```
|
||||||
|
|
||||||
|
### Plugin Management
|
||||||
|
- **Manager**: lazy.nvim
|
||||||
|
- **Check status**: `:Lazy`
|
||||||
|
- **Update**: `:Lazy update`
|
||||||
|
- **Clean**: `:Lazy clean`
|
||||||
|
- **Profile**: `:Lazy profile`
|
||||||
|
|
||||||
|
### Commit Messages
|
||||||
|
- Follow conventional commit format when possible
|
||||||
|
- Be descriptive about Neovim-specific changes
|
||||||
|
- Reference plugin names and features clearly
|
||||||
|
|
||||||
|
### Plugin Configuration Pattern
|
||||||
|
```lua
|
||||||
|
return {
|
||||||
|
'author/plugin-name',
|
||||||
|
event = 'VimEnter', -- Lazy loading trigger
|
||||||
|
dependencies = { 'dep1', 'dep2' },
|
||||||
|
opts = { -- Simple options
|
||||||
|
setting = value,
|
||||||
|
},
|
||||||
|
config = function() -- Complex setup
|
||||||
|
local plugin = require('plugin')
|
||||||
|
plugin.setup({
|
||||||
|
-- Configuration
|
||||||
|
})
|
||||||
|
end,
|
||||||
|
keys = { -- Keybindings
|
||||||
|
{ '<leader>key', function() end, desc = 'Description' },
|
||||||
|
},
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Development Workflow
|
||||||
|
|
||||||
|
1. **Setup**: Clone repository and start Neovim
|
||||||
|
2. **Plugin management**: Use `:Lazy` commands for plugin operations
|
||||||
|
3. **Testing changes**: `:checkhealth`, `:Lazy`, manual testing
|
||||||
|
4. **Formatting**: Use `<leader>f` or conform commands
|
||||||
|
5. **Linting**: Use lint commands for supported file types
|
||||||
|
6. **Git workflow**: Standard branching, commit, and PR process
|
||||||
|
|
||||||
|
## Neovim-Specific Considerations
|
||||||
|
|
||||||
|
- **API usage**: Prefer `vim.api.nvim_*` functions over deprecated `vim.*`
|
||||||
|
- **Version compatibility**: Target latest stable Neovim
|
||||||
|
- **Plugin compatibility**: Check lazy-lock.json for pinned versions
|
||||||
|
- **Performance**: Be mindful of startup time and memory usage
|
||||||
|
- **User experience**: Consider both mouse and keyboard workflows
|
||||||
|
|
||||||
|
This guide ensures AI agents can contribute effectively to this Neovim configuration while maintaining consistency with existing patterns and conventions.
|
||||||
Loading…
Reference in New Issue