From 402fc44008c8e1f29afc43fd26a8119854d13397 Mon Sep 17 00:00:00 2001
From: Stefan VanBuren <svanburen@buf.build>
Date: Thu, 26 Mar 2026 11:49:23 -0400
Subject: [PATCH] Add CONTRIBUTING.md and instructions for agents

This adds a fairly straightforward CONTRIBUTING.md, based on [the one in
connect-go][1]. It adds it at the repo root as opposed to .github/ as
a stronger signal to agents.

This also adds an AGENTS.md file with a light suggestion to agents to
push back on creating PRs that modify public APIs without discussing in
an issue first. We're approaching a stable API and want to carefully
consider what we add at this point. We could carve out an "exception"
for maintainers, but it's probably good for us maintainers to also
consider future additions in an issue first anyway.

Lastly, adds a CLAUDE.md that just `@` includes the AGENTS.md file
(AFAIK, this is still the de-facto way to make this work with `claude`;
we could also just symlink the files).

With all of this, I suspect we can continue to refine these as we go,
but this feels like a decent first step. Open to suggestions here, as
this is all very new/fuzzy.

Ref: https://agents.md/

[1]: https://github.com/connectrpc/connect-go/blob/main/.github/CONTRIBUTING.md

Signed-off-by: Stefan VanBuren <svanburen@buf.build>
---
 AGENTS.md       | 12 +++++++++
 CLAUDE.md       |  1 +
 CONTRIBUTING.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 85 insertions(+)
 create mode 100644 AGENTS.md
 create mode 100644 CLAUDE.md
 create mode 100644 CONTRIBUTING.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..0cc2c0b
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,12 @@
+# AGENTS.md
+
+This file provides guidance to agentic coding assistants like Claude Code (claude.ai/code) when
+working with code in this repository.
+
+## Important: Propose API Changes Before Implementing
+
+Before making or proposing changes to any public API, open a GitHub issue to describe the
+proposal and gather feedback.
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for details.
+
+Do not create pull requests for public API changes without a corresponding issue.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..43c994c
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..9975393
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,72 @@
+# Contributing to connect-python
+
+## Before You Contribute
+
+If you're planning to add or change a public API, please open an issue describing your
+proposal before starting work.
+This helps ensure alignment with the project's direction and makes the review process
+smoother for everyone.
+
+## Developer Certificate of Origin
+
+All commits must be signed off to affirm compliance with the
+[Developer Certificate of Origin](https://developercertificate.org/).
+Configure your git identity to match your GitHub account, then use the `-s` flag when
+committing:
+
+```console
+$ git commit -s -m "your commit message"
+```
+
+## Setting Up Your Development Environment
+
+### Prerequisites
+
+- Python 3.10 or later
+- [uv](https://docs.astral.sh/uv/) for dependency management
+- [just](https://just.systems/) for running tasks
+
+### Installation
+
+1. Fork and clone the repository:
+
+   ```console
+   $ gh repo fork connectrpc/connect-python --clone
+   $ cd connect-python
+   ```
+
+2. Verify everything is working:
+
+   ```console
+   $ uv run just check
+   ```
+
+## Development Workflow
+
+We use `just` as our task runner.
+Run `uv run just --list` to see all available commands.
+
+## Submitting a Pull Request
+
+1. Create a feature branch from an up-to-date `main`:
+
+   ```console
+   $ git checkout -b your-feature-branch
+   ```
+
+2. Make your changes and ensure all checks pass:
+
+   ```console
+   $ uv run just check
+   ```
+
+3. Commit with a sign-off and a clear message, then push to your fork and open a pull
+   request.
+
+Pull requests are more likely to be accepted when they:
+
+- Include tests for new functionality
+- Maintain backward compatibility
+- Have clear commit messages
+
+We aim to respond to issues and pull requests within a few business days.