CrazyClaude/AGENTS.md

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