mirror
/
kickstart.nvim
mirror of https://github.com/nvim-lua/kickstart.nvim.git
1
0
Fork 1
Code Issues Packages Projects Releases Wiki Activity

docs: streamline AGENTS.md for AI coding agents 

- Reduce length from 244 to ~150 lines while preserving all essential info
- Consolidate build/lint/test commands section
- Streamline code style guidelines and combine related sections
- Simplify plugin configuration examples
- Add CI information and clarify testing status
- Maintain comprehensive coverage for AI agent development
This commit is contained in:
Juanito 2026-03-09 22:39:27 +00:00
parent 218aa14756
commit cde327c7ac
No known key found for this signature in database
1 changed files with 39 additions and 136 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

171
AGENTS.md
View File

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