Add AGENTS.md file

[strawgate]

Adds comprehensive AGENTS.md file providing development guidelines, workflows, and context specifically for AI coding agents.

This file complements the existing README.md and DEVELOPING.md by consolidating:

• Development workflow and pre-commit requirements
• Async-first architecture constraints
• Monorepo structure and package organization
• Code style conventions (Ruff, Basedpyright, Beartype)
• Common pitfalls (ManagedEntry, sync codegen, Python version)
• Make commands reference
• Key protocols, stores, wrappers, and adapters

The file follows the emerging AGENTS.md standard from OpenAI and others, making it compatible with modern AI coding assistants while remaining useful as human-readable documentation.

Closes #127

---

Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added comprehensive development guidelines covering workflow procedures, pre-commit checks, testing standards, architecture constraints, code style conventions, and available development commands and tools.

[coderabbitai]

📝 Walkthrough

Walkthrough

Added AGENTS.md documentation file outlining guidelines for AI coding agents, covering development workflow, testing requirements, architecture constraints, code style conventions, project structure, backend dependencies, and instructions for make commands and repository operations.

Changes

Cohort / File(s)	Summary
Documentation AGENTS.md	New guidelines and context documentation for AI coding agents including development workflows, architecture constraints (async-first design with generated sync code), code style conventions, testing requirements, project structure, optional backend dependencies, make command instructions, and repository resources

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The pull request title "Add AGENTS.md file" directly and clearly summarizes the main change in the changeset. The raw summary confirms that a new AGENTS.md documentation file was added to the repository, containing comprehensive guidelines and context for AI coding agents. The title is concise, specific, and accurately reflects the primary objective of the pull request.
Linked Issues Check	✅ Passed	The pull request successfully fulfills the requirements of linked issue #127, which requests adding an agents.md file. The raw summary confirms that AGENTS.md was added with all the anticipated content, including development workflow guidelines, architecture constraints, monorepo structure, code style conventions, common pitfalls, and references for AI coding agents working on the project. The PR description notes this change closes issue #127, and the implementation aligns with the stated objective of providing development guidelines and context for AI coding assistants.
Out of Scope Changes Check	✅ Passed	The pull request contains only the addition of the AGENTS.md file, which is directly in scope with the linked issue #127. The raw summary confirms there are no alterations to exported or public entity declarations and no modifications to other files in the repository. All changes are focused on the single objective of adding the new documentation file for AI coding agents.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch claude/issue-127-20251026-0650

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 0d790a6 and 8abf084.

📒 Files selected for processing (1)

• AGENTS.md (1 hunks)

🧰 Additional context used

🪛 LanguageTool

AGENTS.md

[uncategorized] ~212-~212: The official name of this software platform is spelled with a capital “H”.
Context: ... CI/CD GitHub Actions workflows are in .github/workflows/: - test.yml - Run tests ...

(GITHUB)

🔇 Additional comments (8)

AGENTS.md (8)

1-5: Clear purpose and audience definition. The introduction properly signals this document's intended audience and cross-references human documentation.

---

6-29: Development workflow is clear and emphasizes critical constraints. The explicit requirement to run make codegen as a pre-commit check appropriately prevents committing async-only changes without syncing to the generated package.

---

57-72: Code style guidance is comprehensive and includes escape hatch for Beartype. Line 66 appropriately documents the environment variable to disable runtime type checking for edge cases, and the 3.10+ minimum is clearly noted as a constraint for sync codegen.

---

189-227: Development environment and operational guidance is complete. DevContainer recommendation and local setup prerequisites are clear. CI/CD section appropriately references workflow files without over-documenting their contents.

---

210-217: Note: Static analysis false positive. LanguageTool flagged line 212 about GitHub capitalization, but "GitHub Actions" is already correctly capitalized. No change needed.

---

30-55: Architecture documentation is accurate. All referenced file paths have been verified:

• ✓ scripts/build_sync_library.py exists
• ✓ scripts/bump_versions.py exists
• ✓ All monorepo directories (key-value-aio, key-value-sync, key-value-shared, key-value-shared-test) exist in the expected locations

The async-first constraint and monorepo structure documentation is correct and current.

---

73-110: Path reference is accurate for documentation context. The key_value/shared/utils/managed_entry.py path correctly represents the import/package path, which is the appropriate form for user-facing documentation in AGENTS.md. The file exists at key-value/key-value-shared/src/key_value/shared/utils/managed_entry.py in the repository structure, and the documented path omits repository-specific directory prefixes as expected. All common pitfalls are well-articulated with accurate references.

---

111-188: All documented file paths are accurate. Verification confirms that the protocol file locations (lines 143, 153), store directories (lines 160-161), wrapper directories (lines 170-171), and adapter directories (lines 181-182) all exist and match the documentation exactly. The make commands reference and component overview are correct as written.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud