TheRock/rocm-libraries/projects/rocblas/AGENT_RULES_README.md

rocBLAS Agent Development Rules

This directory contains agent development rules for AI coding assistants (Cursor, Cline, GitHub Copilot) working with the rocBLAS project.

📁 Files Overview

Core Rules

• .cursorrules - Main rules file for Cursor/Cline (15 KB)
  • Complete project overview and architecture
  • Build and testing quickstart (Linux + Windows)
  • C++ code style guidelines
  • Development workflow and best practices

Cursor-Specific Rules (.cursor/rules/)

• rocblas-architecture.mdc (3 KB) - alwaysApply: true

  • BLAS operation levels (1, 2, 3, Extensions)
  • Tensile integration
  • Data type support
  • Component organization

• building.mdc (4 KB) - alwaysApply: false

  • Build commands (install.sh, rmake.py)
  • Test execution (rtest.py)
  • Test levels (smoke, psdb, osdb, cqe)
  • Performance benchmarking

• cpp-style.mdc (6 KB) - globs: ["*.cpp", "*.hpp", "*.h"]

  • Naming conventions (snake_case)
  • BLAS API patterns
  • HIP/GPU code examples
  • MIT license header template

• testing.mdc (7 KB) - globs: ["*.cpp", "*.hpp", "*.h", "clients/gtest/**"]

  • Google Test patterns
  • YAML test configuration
  • Test categories and filters
  • Multi-OS testing framework

GitHub Copilot

• .github/copilot-instructions.md (7 KB)
  • Condensed rules for GitHub Copilot
  • Quick reference for common patterns
  • API examples and build commands

Documentation

• AGENT_RULES_README.md (this file)
  • Quick overview of all files
  • Getting started guide

🚀 Quick Start

For Cursor/Cline Users

1. Open any rocBLAS file - Rules activate automatically
2. Ask about the project:
   • "Explain the rocBLAS architecture"
   • "How do I build rocBLAS on Linux?"
   • "What are the test levels?"
3. Request code changes:
   • "Add a new BLAS Level 1 operation"
   • "Create a test for gemm_strided_batched"
4. Build and test:
   • "Build rocBLAS with clients"
   • "Run smoke tests"

For GitHub Copilot Users

GitHub Copilot will automatically read .github/copilot-instructions.md and provide context-aware suggestions following rocBLAS conventions.

📖 What Agents Know

Project Structure

• Library components (blas1, blas2, blas3, blas_ex)
• Client structure (gtest, benchmarks, samples)
• Tensile integration for GEMM operations
• Documentation and scripts

Build System

• Linux: ./install.sh with various flags
• Windows: python rmake.py (with HIP_PATH set)
• Architecture flags (--architecture auto)
• Dependency management

Testing

• Test Levels:
  • smoke (5-10 min) - Quick sanity
  • psdb (30-60 min) - PR validation
  • osdb (1.5-2 hrs) - Nightly regression
  • cqe (3-3.5 hrs) - Complete QE
• Test Execution: rtest.py -t <level>
• Direct Testing: rocblas-test --gtest_filter=*pattern*
• YAML Configuration: Parameterized test definitions

Code Style

• Naming: snake_case for functions/variables
• BLAS Convention: rocblas_<precision><operation>
• Precisions: s=float, d=double, c=complex, z=complex double, h=half, bf16=bfloat16
• Headers: Full MIT license header
• Include Guards: #pragma once

Testing Workflow

• Test Orchestration: rtest.py with multiple test levels
• Direct Testing: rocblas-test with gtest filters
• YAML Configuration: Parameterized test definitions
• Benchmarking: rocblas-bench for performance testing

🎯 Key Features

1. BLAS-Specific Conventions

Unlike hipDNN's CamelCase, rocBLAS uses snake_case to match traditional BLAS naming standards.

2. Dual Platform Support

Comprehensive documentation for both Linux (primary) and Windows development.

3. Test Hierarchy

Clear progression from quick smoke tests to comprehensive QE validation.

4. Performance Focus

Includes benchmarking guidance and Tensile kernel optimization.

🔧 Customization

To Modify Rules:

1. General changes: Edit .cursorrules
2. Architecture info: Edit .cursor/rules/rocblas-architecture.mdc
3. Build/test commands: Edit .cursor/rules/building.mdc
4. Code style: Edit .cursor/rules/cpp-style.mdc
5. Testing patterns: Edit .cursor/rules/testing.mdc
6. GitHub Copilot: Edit .github/copilot-instructions.md

To Add New Rules:

Create new .mdc files in .cursor/rules/ with appropriate metadata:

---
alwaysApply: false
globs: ["*.cpp", "*.hpp"]
---

# Your Rule Title

Your rule content here...

📊 Comparison to hipDNN

Aspect	hipDNN	rocBLAS
Naming	CamelCase	snake_case
Build	CMake + Ninja	install.sh / rmake.py
Testing	Direct binaries	rtest.py orchestration
Platform	Linux	Linux + Windows
Architecture	Plugin-based	BLAS levels
Special	Graph operations	Tensile kernels

See AGENT_RULES_COMPARISON.md for detailed comparison.

💡 Tips for Agents

When Suggesting Code:

1. ✅ Use snake_case naming
2. ✅ Follow rocblas_<precision><operation> pattern
3. ✅ Include full MIT license header
4. ✅ Add tests in clients/gtest/
5. ✅ Consider all data types (s, d, c, z, h, bf16)
6. ✅ Use #pragma once for headers

When Building:

1. ✅ Use ./install.sh on Linux
2. ✅ Use python rmake.py on Windows
3. ✅ Add --architecture auto for faster builds
4. ✅ Only build when explicitly requested

When Testing:

1. ✅ Start with rtest.py -t smoke
2. ✅ Use appropriate test level for context
3. ✅ Use --gtest_filter for specific tests
4. ✅ Use YAML configs for parameterized testing

📚 Additional Resources

• rocBLAS Documentation: docs/
• Build Guides: docs/install/
• Test Configuration: rtest.xml - Test suite definitions
• YAML Test Files: clients/gtest/*.yaml - Parameterized test configurations

🤝 Contributing

For Developers Updating Rules

When updating these rules:

1. Test with actual agent interactions
2. Update all relevant files (don't forget copilot-instructions.md)
3. Document changes in this README
4. Consider impact on both Cursor and GitHub Copilot

For AI Agents Using These Rules

Help improve these rules! If you notice:

• ✅ Inconsistencies: Pattern in code differs from documented rule
• ✅ Missing patterns: Critical idioms not documented
• ✅ Outdated examples: Code examples don't match current practices
• ✅ Gaps: Questions these rules should answer but don't

Suggest updates by saying:

"I notice [observation]. The rules in [file] section [section] should be updated to [suggestion]. This will help future agents [benefit]."

This creates a continuous improvement loop where the rules evolve with the codebase.

✅ Verification

To verify the rules are working:

1. Open a rocBLAS file in Cursor
2. Ask: "What are the BLAS operation levels?"
3. Expected: Agent should reference Level 1, 2, 3, and Extensions
4. Ask: "How do I build rocBLAS?"
5. Expected: Agent should provide platform-specific commands

📝 Version History

• 2026-01-02: Initial creation based on hipDNN rules
  • Adapted naming conventions for BLAS
  • Added dual platform support
  • Documented rtest.py test orchestration
  • Documented test hierarchy and YAML configurations
  • Added Windows-specific guidance

🙏 Credits

These rules were inspired by the hipDNN project's agent development rules and adapted specifically for rocBLAS development workflows and testing infrastructure.

---

Questions? See AGENT_RULES_SUMMARY.md for detailed documentation.