feat: Add/update AGENTS.md for AI agent guidance

.agentic-config.json

@@ -0,0 +1,134 @@
+{
+  "metadata": {
+    "project_name": "anthropic-sdk-python",
+    "description": "A Python project with Python (hatchling)",
+    "generated_by": "Braxis",
+    "generated_at": "2026-10-09T00:43:23.790361",
+    "schema_version": "1.0"
+  },
+  "project": {
+    "languages": [
+      "python"
+    ],
+    "primary_language": "python",
+    "build_system": "Python (hatchling)",
+    "architecture": "single-package",
+    "is_monorepo": false,
+    "monorepo_type": null,
+    "subsystems": []
+  },
+  "ai_readiness": {
+    "overall_score": 70,
+    "tier": "AI-Native-Plus",
+    "dimensions": {
+      "architecture": {
+        "score": 0,
+        "reason": "Code organization and modularity"
+      },
+      "testing": {
+        "score": 15,
+        "reason": "256 test files found"
+      },
+      "dependencies": {
+        "score": 12,
+        "reason": "Dependency management and version pinning"
+      },
+      "conventions": {
+        "score": 10,
+        "reason": "Consistency in naming and patterns"
+      },
+      "entry_points": {
+        "score": 0,
+        "reason": "0 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": "pip install -e . && uv sync --all-groups",
+    "test_command": "pytest",
+    "lint_command": "ruff check .",
+    "format_command": "ruff format .",
+    "dev_server_command": null,
+    "prerequisites": {
+      "language_version": "3.9+",
+      "package_manager": "pip or uv",
+      "key_tools": [
+        "pytest",
+        "ruff",
+        "mypy"
+      ]
+    }
+  },
+  "architecture": {
+    "pattern": "single-package project",
+    "main_entry": "Standard layout",
+    "key_modules": [],
+    "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": "pip install -e . && uv sync --all-groups",
+      "description": "Install dependencies and set up development environment"
+    },
+    "test": {
+      "command": "pytest",
+      "description": "Run all tests"
+    },
+    "lint": {
+      "command": "ruff check .",
+      "description": "Check code style and quality"
+    },
+    "format": {
+      "command": "ruff format .",
+      "description": "Format code to project standards"
+    }
+  },
+  "testing": {
+    "framework": "pytest",
+    "total_tests": 256,
+    "pass_rate": 100,
+    "run_command": "pytest"
+  }
+}

.cursorrules

@@ -0,0 +1,77 @@
+# Cursor Rules for anthropic-sdk-python
+
+## What This Project Does
+
+**Language:** Python | **Build:** Python (hatchling)
+
+**AI Readiness Score:** 70/100 (AI-Native-Plus)
+
+## Must-Follow Rules
+
+### Code Style & Formatting
+
+1. Use **ruff** for formatting: `ruff format .`
+2. Use **ruff** for linting: `ruff check .`
+3. Python conventions: **snake_case** for functions/variables, **PascalCase** for classes
+4. Type hints: Required for all public functions using **mypy** for checking
+5. Docstrings: Use triple-quoted strings for all public functions and classes
+6. No commented-out code, no dead code
+7. Max line length: 100 characters
+
+### Testing
+1. Framework: pytest
+2. Test file naming: `test_*.py` or `*_test.py`
+3. Test discovery: `pytest` finds and runs all tests
+4. Fixtures: Use pytest fixtures for setup/teardown
+5. Coverage: Maintain 80%+ coverage for critical paths
+6. Run before commit: `pytest -v`
+
+### Imports & Dependencies
+1. Use absolute imports, not relative imports (unless necessary)
+2. Group imports: stdlib, third-party, local (isort style)
+3. No wildcard imports (`from module import *`)
+4. Pin versions in requirements.txt/pyproject.toml
+5. Avoid circular dependencies
+
+### Error Handling
+1. Be specific with exception types (not bare `except:`)
+2. Log errors before re-raising
+3. Validate all function arguments at entry points
+4. Use try/except at system boundaries (I/O, network, DB)
+
+
+## Scoring Dimensions (What Matters)
+
+These 8 areas drive AI readiness. Focus on these when making changes:
+
+1. **Architecture** (0/15) - Code organization and modularity
+2. **Testing** (15/15) - Test coverage and quality
+3. **Dependencies** (12/12) - Dependency management
+4. **Conventions** (10/10) - Consistent patterns
+5. **Entry Points** (0/10) - Clear main/start locations
+6. **Security** (10/15) - Input validation and error handling
+7. **Build** (10/10) - Clear build/setup instructions
+8. **Documentation** (8/8) - Code and project documentation
+
+## Before You Commit
+
+```bash
+# Format code
+ruff format .
+
+# Lint check
+ruff check .
+
+# Run tests
+pytest
+```
+
+All checks must pass before committing.
+
+## Questions?
+
+See AGENTS.md for detailed documentation on architecture, development workflow, and testing strategy.
+
+---
+
+*Generated by Braxis - language-aware rules for Python projects*