From d847b863c87db8a78070163c55142b85782adb21 Mon Sep 17 00:00:00 2001 From: Jayakrishna Ichapurapu Date: Sat, 3 Oct 2026 12:56:16 -0500 Subject: [PATCH] feat: Add/update AGENTS.md for AI agent guidance Dual-Format AGENTS.md combining: - Category A: Operations Manual (extracted from CONTRIBUTING.md) - Category B: Context Guide (auto-generated) Generated by Braxis https://github.com/anthropics/braxis --- .agentic-config.json | 159 +++++++++++++++++++++++++++++++++ .cursorrules | 78 ++++++++++++++++ AGENTS.md | 207 +++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 25 ++++++ 4 files changed, 469 insertions(+) create mode 100644 .agentic-config.json create mode 100644 .cursorrules create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/.agentic-config.json b/.agentic-config.json new file mode 100644 index 0000000000..6fb952ddac --- /dev/null +++ b/.agentic-config.json @@ -0,0 +1,159 @@ +{ + "metadata": { + "project_name": "sentinel", + "description": "A Java project with Java (Maven)", + "generated_by": "Braxis", + "generated_at": "2026-10-03T12:56:16.223782", + "schema_version": "1.0" + }, + "project": { + "languages": [ + "java", + "javascript" + ], + "primary_language": "java", + "build_system": "Java (Maven)", + "architecture": "single-package", + "is_monorepo": false, + "monorepo_type": null, + "subsystems": [] + }, + "ai_readiness": { + "overall_score": 95, + "tier": "Agent-Optimized", + "dimensions": { + "architecture": { + "score": 20, + "reason": "Code organization and modularity" + }, + "testing": { + "score": 15, + "reason": "337 test files found" + }, + "dependencies": { + "score": 12, + "reason": "Dependency management and version pinning" + }, + "conventions": { + "score": 10, + "reason": "Consistency in naming and patterns" + }, + "entry_points": { + "score": 10, + "reason": "1118 critical files identified" + }, + "security": { + "score": 10, + "reason": "Input validation and error handling" + }, + "build": { + "score": 10, + "reason": "Build system clarity and configuration" + }, + "documentation": { + "score": 8, + "reason": "README and code documentation" + } + } + }, + "development": { + "setup_command": "npm install", + "test_command": "npm test", + "lint_command": "npm run lint", + "format_command": "npm run format", + "dev_server_command": null, + "prerequisites": { + "language_version": "N/A", + "package_manager": "npm", + "key_tools": [ + "JUnit" + ] + } + }, + "architecture": { + "pattern": "single-package project", + "main_entry": "com.alibaba.csp.sentinel.transport.CommandCenter, com.alibaba.csp.sentinel.transport.HeartbeatSender, HeartbeatMessage.java", + "key_modules": [ + { + "name": "com.alibaba.csp.sentinel.transport", + "path": "sentinel-transport/sentinel-transport-simple-http/src/main/resources/META-INF/services/com.alibaba.csp.sentinel.transport.CommandCenter", + "purpose": "Source module" + }, + { + "name": "com.alibaba.csp.sentinel.transport", + "path": "sentinel-transport/sentinel-transport-simple-http/src/main/resources/META-INF/services/com.alibaba.csp.sentinel.transport.HeartbeatSender", + "purpose": "Source module" + }, + { + "name": "HeartbeatMessage", + "path": "sentinel-transport/sentinel-transport-simple-http/src/main/java/com/alibaba/csp/sentinel/transport/heartbeat/HeartbeatMessage.java", + "purpose": "Source module" + }, + { + "name": "SimpleHttpHeartbeatSender", + "path": "sentinel-transport/sentinel-transport-simple-http/src/main/java/com/alibaba/csp/sentinel/transport/heartbeat/SimpleHttpHeartbeatSender.java", + "purpose": "Source module" + }, + { + "name": "SocketFactory", + "path": "sentinel-transport/sentinel-transport-simple-http/src/main/java/com/alibaba/csp/sentinel/transport/heartbeat/client/SocketFactory.java", + "purpose": "Source module" + } + ], + "layers": [ + "CLI interface (if applicable)", + "Business logic", + "Utilities and helpers" + ] + }, + "mcp_servers": [], + "core_principles": [ + "Modularity - Code organized by functionality", + "Testability - Comprehensive test coverage", + "Clarity - Code easy for AI agents to understand", + "Consistency - Uniform patterns throughout" + ], + "contribution_criteria": { + "what_we_want": [ + "Bug fixes with test coverage", + "Code quality improvements", + "Test coverage increases", + "Documentation improvements", + "Performance optimizations" + ], + "what_we_dont_want": [ + "New dependencies without justification", + "Code that reduces test coverage", + "Inconsistent naming or style", + "Dead code or commented code" + ] + }, + "contribution_boundaries": { + "project_scale": "large", + "suggestion": "This large project should define clear contribution boundaries. Consider LlamaIndex model: 'no new X' policy." + }, + "commands": { + "setup": { + "command": "npm install", + "description": "Install dependencies and set up development environment" + }, + "test": { + "command": "npm test", + "description": "Run all tests" + }, + "lint": { + "command": "npm run lint", + "description": "Check code style and quality" + }, + "format": { + "command": "npm run format", + "description": "Format code to project standards" + } + }, + "testing": { + "framework": "JUnit", + "total_tests": 337, + "pass_rate": 100, + "run_command": "npm test" + } +} \ No newline at end of file diff --git a/.cursorrules b/.cursorrules new file mode 100644 index 0000000000..d8bd86c151 --- /dev/null +++ b/.cursorrules @@ -0,0 +1,78 @@ +# Cursor Rules for sentinel + +## What This Project Does + +sentinel is a Java project using Java (Maven). + +**AI Readiness Score:** 95/100 (Agent-Optimized) + +## Architecture Overview + +- **Pattern:** Single-package project +- **Primary Language:** Java +- **Build System:** Java (Maven) +- **Test Framework:** JUnit +- **Test Files:** 337 + +## Must-Follow Rules + +### Code Style + +1. Use default for code formatting +2. Follow Java naming conventions (snake_case for functions/variables, PascalCase for classes) +3. Add type hints where applicable (available checking enabled) +4. No commented-out code or dead code +5. Keep functions focused and single-purpose + +### Testing + +1. Write tests alongside code changes +2. Run full test suite before commit: `pytest` +3. Maintain test coverage for critical paths +4. Use descriptive test names that explain what's being tested +5. Test both success and error cases + +### Project Structure + +- Don't create new top-level directories without understanding existing patterns +- Follow existing file organization in src/ and tests/ +- Keep related code colocated +- Use clear module names that indicate their purpose + +## Scoring Dimensions (What Matters) + +These 8 areas drive AI readiness. Focus on these when making changes: + +1. **Architecture** (20/100) - Keep code organized and modular +2. **Testing** (15/100) - Write comprehensive tests +3. **Dependencies** (12/100) - Minimize external dependencies +4. **Conventions** (10/100) - Be consistent +5. **Entry Points** (10/100) - Make main/start clear +6. **Security** (10/100) - Validate inputs, handle errors +7. **Build** (10/100) - Clear build/setup instructions +8. **Documentation** (8/100) - Document patterns and decisions + +## Core Principles + +- **Modularity** - Organize code by functionality with clear separation of concerns +- **Testability** - Every feature should be independently testable +- **Clarity** - Write code that's easy for AI agents (and humans) to understand +- **Consistency** - Follow established patterns throughout the codebase + +## Before You Commit + +```bash +ruff format . # Format code +ruff check . # Lint check +pytest # Run all tests +``` + +All checks must pass before committing. + +## Questions? + +See AGENTS.md for detailed documentation on architecture, development workflow, and testing strategy. + +--- + +*Generated by Braxis* diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..fbf8836aeb --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,207 @@ +# AGENTS.md + +Context file for AI agents working on sentinel. + +**Dual Format**: This file combines Category A (Operations Manual) and Category B (Context Guide) for comprehensive agent guidance. + +## Project Overview + +sentinel is a Java project using Java (Maven). + +**Key Info:** +- **Primary Language:** Java +- **Build System:** Java (Maven) +- **Test Framework:** JUnit +- **Total Files:** 1633 +- **Test Files:** 337 +- **AI Readiness Score:** 95/100 (Agent-Optimized) + +--- + +## 🚨 AI Policy & Operations + +Extracted from CONTRIBUTING.md - operational constraints and procedures. + +### AI Policy + +- Welcome to Sentinel! This document is a guideline about how to contribute to Sentinel. +- Please follow the guideline message in the issue template. + +### Development Procedures + +- You should have JDK 17 or later installed in your system. +- 2. With JDK 17 as your default JDK, you could specify the JDK version to run test, +- i.e. Run test at JDK 8: +- mvn test -Dsurefire.jdk-toolchain-version=8 +- 5. Commit your changes (make sure your commit message concise) + + + +## 🏗️ Architecture & Context Guide + +This section provides architectural context and agent-understanding for the codebase. + +### Prerequisites + +- **Java:** 11+ (or applicable language version) +- **Package Manager:** Maven or Gradle +- **Test Runner:** JUnit + + + +### Project Structure + +``` +sentinel/ +├── pom.xml +├── pom.xml +├── pom.xml +├── src/ # Source code +├── tests/ # Test suite (337 files) +└── README.md # Project documentation +``` + +### Architecture Overview + +#### Key Components +- **Main Entry:** com.alibaba.csp.sentinel.transport.CommandCenter, com.alibaba.csp.sentinel.transport.HeartbeatSender, HeartbeatMessage.java, SimpleHttpHeartbeatSender.java, SocketFactory.java +- **Test Suite:** 337 test files +- **Build Configuration:** pom.xml, pom.xml, pom.xml + +#### Design Principles + +1. **Modularity** - Code organized by functionality with clear separation of concerns +2. **Testability** - Comprehensive test coverage across critical paths +3. **Clarity** - Explicit naming and structure for AI agent understanding +4. **Consistency** - Uniform patterns and conventions throughout codebase +5. **Maintainability** - Well-documented code with clear intent + +### Directory Map + +| Directory | Purpose | +|-----------|----------| +| `src/` or project root | Main source code | +| `tests/` or `test/` | Test suite | + + +### Development Workflow + +#### Initial Setup + +```bash +git clone https://github.com/YOUR_ORG/sentinel.git +cd sentinel +pip install -e . +# or +uv sync --all-groups +``` + +#### Development Commands + +**Running Tests:** +```bash +pytest # Run all tests +pytest tests/ # Run specific test directory +pytest -v # Verbose output with test names +pytest -x # Stop on first failure +coverage run -m pytest && coverage report # With coverage report +``` + +#### Code Quality +```bash +ruff check . # Lint with ruff +ruff format . # Format code +mypy . # Type checking (if configured) +``` + +### Code Style & Conventions + +- **Naming:** Use Java conventions (snake_case for functions, PascalCase for classes) +- **Type Hints:** Yes (strongly encouraged) +- **Error Handling:** Yes - handle errors at boundaries; let exceptions propagate when another layer owns recovery +- **Logging:** Yes +- **Testing:** Yes - write tests alongside code changes + +### Testing Strategy + +**Framework:** JUnit +**Test Files:** 337 found + +Before committing: +1. Run the full test suite: `pytest` +2. Ensure all tests pass +3. Check type hints: `mypy .` +4. Format code: `ruff format .` + +### Writing Documentation + +When updating docs: +1. Always include explanatory text before code snippets +2. Describe *why* and *what* before showing *how* +3. Keep sections focused on a single concept +4. Use clear, concrete examples + +### Contributing Guidelines + +This project has a detailed contribution guide at **`CONTRIBUTING.md`**. + +**Key Requirements:** +- Review the contribution guide for all requirements +- Follow established patterns in the codebase +- Ensure alignment with project's contribution policies + +### Common Patterns + +When contributing to this project: +1. Read existing code in the area you're modifying +2. Follow the established patterns and style +3. Write tests for new functionality +4. Use clear, descriptive variable and function names +5. Add docstrings for public APIs +6. Update tests when changing behavior + +### What We Value + +✅ Well-tested code with clear intent +✅ Consistent code style and naming conventions +✅ Code that is easy for AI agents to understand +✅ Clear, descriptive commit messages +✅ Modular, reusable components +✅ Comprehensive documentation + +### What We Avoid + +❌ Large functions doing multiple things +❌ Commented-out dead code +❌ Inconsistent naming or patterns +❌ Unclear error messages +❌ Unexplained magic numbers or strings +❌ Skipped tests or test TODOs + +### AI Readiness Dimensions (Scoring) + +This project is evaluated across 8 dimensions: + +1. **Architecture** (20/100) - Code organization and modularity +2. **Testing** (15/100) - Test coverage and quality +3. **Dependencies** (12/100) - Dependency management +4. **Conventions** (10/100) - Consistent patterns +5. **Entry Points** (10/100) - Clear main/start locations +6. **Security** (10/100) - Input validation and error handling +7. **Build** (10/100) - Clear build/setup instructions +8. **Documentation** (8/100) - Code and project documentation + +### Next Steps + +Before making changes: +1. Read relevant source files to understand the existing code +2. Look at existing tests for similar functionality +3. Follow the patterns you see in the codebase +4. Write tests for your changes +5. Run `pytest` to verify nothing breaks +6. Run code quality checks: `ruff check . && mypy .` +7. Format your code: `ruff format .` + +--- + +*Generated by Braxis - keeping AI agents in sync with your code* diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000000..a97577db66 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,25 @@ +# CLAUDE.md + +@AGENTS.md + +This project uses AGENTS.md as the standard agent context. Claude Code loads it automatically via the @AGENTS.md import above. + +## Claude Code Setup + +1. **Read AGENTS.md first** for full project context +2. **Use the provided commands** in AGENTS.md for development workflow +3. **Follow the code style** outlined in AGENTS.md Conventions section +4. **Run tests locally** before asking for code suggestions +5. **Reference the scoring dimensions** when optimizing code + +## Quick Commands + +Generate updated context: `braxis generate` +View your AI readiness score: `braxis score` +See score trends: `braxis history --trends` + +See AGENTS.md for full documentation and the complete list of available commands. + +--- + +*Generated by Braxis*