91 lines
4.2 KiB
Markdown
91 lines
4.2 KiB
Markdown
|
# AGENTS.md
|
||
|
|
|
||
|
|
This file documents the project's coding standards, build/test/lint commands, and operational guidelines for agentic AI assistants.
|
||
|
|
|
||
|
|
## Build, Lint, and Test Commands
|
||
|
|
|
||
|
|
- **Rust**: `cargo build --all-targets && cargo test --all-targets`
|
||
|
|
- **Go**: `go build ./... && go vet ./... && go test ./...`
|
||
|
|
- **Python**: `python -m pytest tests/` (single test: `python -m pytest tests/test_module.py::test_function`)
|
||
|
|
- **R**: `Rscript -e "devtools::test()"` (single test: `Rscript -e "testthat::test_file('tests/testthat/test_module.R')"`)
|
||
|
|
- **Bash**: Run tests directly or use `bash -n script.sh` for syntax check
|
||
|
|
|
||
|
|
For all languages: run linters before committing (see hooks in `.claude/hooks/`)
|
||
|
|
|
||
|
|
## Code Style Guidelines
|
||
|
|
|
||
|
|
### General Principles
|
||
|
|
- Follow language-specific idioms and conventions
|
||
|
|
- Prioritize readability over cleverness
|
||
|
|
- Use descriptive names for variables, functions, and types
|
||
|
|
- Keep functions small and focused on a single responsibility
|
||
|
|
|
||
|
|
### Imports and Dependencies
|
||
|
|
- **Rust**: Use `use` statements at top of file; group std, external crates, and local modules
|
||
|
|
- **Go**: Import blocks organized: standard library, then external packages, then local packages
|
||
|
|
- **Python**: Standard library imports first, then third-party, then local imports
|
||
|
|
- **R**: Attach packages with `library()` at top of script; use `pkg::function()` for occasional calls
|
||
|
|
- **Bash**: Source local modules with absolute paths or relative from script location
|
||
|
|
|
||
|
|
### Naming Conventions
|
||
|
|
- **Rust**: Types/CamelCase, functions/snake_case, constants/SCREAMING_SNAKE_CASE
|
||
|
|
- **Go**: Exported names start with uppercase, unexported with lowercase; use CamelCase for acronyms
|
||
|
|
- **Python**: Classes/CamelCase, functions/variables/snake_case; use _private for internal
|
||
|
|
- **R**: Functions/lowercase_with_underscores; avoid naming conflicts with base R functions
|
||
|
|
- **Bash**: Functions/snake_case; variables lowercase; constants UPPERCASE
|
||
|
|
|
||
|
|
### Error Handling
|
||
|
|
- **Rust**: Use `Result<T, E>` and `?` operator; define custom error types for libraries
|
||
|
|
- **Go**: Return `(result, error)` tuple; handle errors immediately after function call
|
||
|
|
- **Python**: Raise specific exception types; catch only what you can handle meaningfully
|
||
|
|
- **R**: Use `stop()` for errors, `warning()` for warnings; consider tryCatch for recovery
|
||
|
|
- **Bash**: Check return codes with `$?`; use `set -e` for strict error handling
|
||
|
|
|
||
|
|
### Types and Documentation
|
||
|
|
- **Rust**: Specify all types explicitly; use `cargo doc` for documentation
|
||
|
|
- **Go**: Document exported functions with comments; use type aliases for clarity
|
||
|
|
- **Python**: Use type hints (PEP 484); docstrings with Google or NumPy style
|
||
|
|
- **R**: Use roxygen2 for function documentation; document all exported functions
|
||
|
|
- **Bash**: Comment complex logic; use `set -x` for debugging trace
|
||
|
|
|
||
|
|
## Cursor Rules
|
||
|
|
|
||
|
|
- Run linters after any file write (see `.claude/hooks/post-write-lint.sh`)
|
||
|
|
- For Rust/Go projects, run `cargo clippy` or `go vet` before committing
|
||
|
|
- Verify tests pass after changes: `cargo test`, `go test`, `pytest`
|
||
|
|
- When modifying multiple files, run full test suite before finalizing
|
||
|
|
|
||
|
|
## Copilot Rules
|
||
|
|
|
||
|
|
- Delegation: Use Qwen3-Coder for atomic tasks via MCP server at port 1248
|
||
|
|
- Code review: Invoke code-reviewer agent for PRs and significant changes
|
||
|
|
- Planning: Use task-planner to break complex tasks into atomic steps
|
||
|
|
- Always verify agent outputs before committing or pushing
|
||
|
|
|
||
|
|
## Hooks and Automation
|
||
|
|
|
||
|
|
- **post-write-lint.sh**: Runs linters after file writes
|
||
|
|
- **subagent-stop-log.sh**: Logs subagent completion and exit codes
|
||
|
|
- **pre-bash-guard.sh**: Validates bash scripts before execution
|
||
|
|
|
||
|
|
## MCP Server Configuration
|
||
|
|
|
||
|
|
- **Endpoint**: `http://localhost:1248`
|
||
|
|
- **Model**: `qwen/qwen3-coder-next`
|
||
|
|
- **Local agent loop**: `.claude/mcp/qwen3-mcp/agent_lm.py`
|
||
|
|
- **Server script**: `.claude/mcp/qwen3-mcp/server.py`
|
||
|
|
|
||
|
|
## Project Structure
|
||
|
|
|
||
|
|
- `.claude/agents/` - Agent definitions (qwen3-worker, code-reviewer, task-planner)
|
||
|
|
- `.claude/skills/` - Domain-specific skills and conventions
|
||
|
|
- `.claude/hooks/` - Git hooks for automated checks
|
||
|
|
- `.claude/mcp/qwen3-mcp/` - MCP server and agent integration
|
||
|
|
|
||
|
|
## Testing Strategy
|
||
|
|
|
||
|
|
- Run tests after any code change
|
||
|
|
- For single test execution, use language-specific commands above
|
||
|
|
- CI/CD should run full test suite on every push
|
||
|
|
- Code coverage targets: 80% minimum for production code
|