|
| 1 | +# Coding Agent Instructions — agent-readable |
| 2 | + |
| 3 | +This repository uses `agent-readable`. Install if needed: `pip install agent-readable` |
| 4 | + |
| 5 | +## Before using or modifying a class or module |
| 6 | + |
| 7 | +Do not guess. Run this first: |
| 8 | + |
| 9 | +```python |
| 10 | +from agent_readable import agent_help |
| 11 | + |
| 12 | +print(agent_help(ClassName)) |
| 13 | +# or: python -m agent_readable package.module:ClassName |
| 14 | + |
| 15 | +# or |
| 16 | +print(agent_help(package.module)) |
| 17 | +# or: python -m agent_readable package.module |
| 18 | +``` |
| 19 | + |
| 20 | +Treat the output as the canonical usage guide. Follow do/don't rules, anti-patterns, and lifecycle constraints exactly. Do not invent behavior that contradicts it. |
| 21 | + |
| 22 | +After modifying a class, prefer docstrings first — only update `__agent_notes__()` for corner cases docstrings cannot express. Verify `agent_help(ClassName)` is still accurate. |
| 23 | + |
| 24 | +## Making a class agent-readable |
| 25 | + |
| 26 | +**New class** — inherit `AgentReadableMixin`: |
| 27 | + |
| 28 | +```python |
| 29 | +from agent_readable import AgentReadableMixin |
| 30 | + |
| 31 | + |
| 32 | +class ResourcePool(AgentReadableMixin): |
| 33 | + """ |
| 34 | + Rotates interchangeable resources such as API keys. |
| 35 | +
|
| 36 | + Agent usage: |
| 37 | + Run ``agent_help(ResourcePool)`` before using this class in generated code. |
| 38 | + """ |
| 39 | + |
| 40 | + def __init__(self, resources, *, cooldown: float = 60): ... |
| 41 | + |
| 42 | + def call(self, fn): |
| 43 | + """Call fn(resource) with automatic rotation and retry.""" |
| 44 | + |
| 45 | + @classmethod |
| 46 | + def __agent_notes__(cls) -> str: |
| 47 | + return """ |
| 48 | +## Do |
| 49 | +
|
| 50 | +- Use `call()` for normal non-streaming requests. |
| 51 | +
|
| 52 | +## Do not |
| 53 | +
|
| 54 | +- Do not use for streaming requests. |
| 55 | +""" |
| 56 | +``` |
| 57 | + |
| 58 | +**Wrapping an existing class** — just mix in: |
| 59 | + |
| 60 | +```python |
| 61 | +class Connection(sqlite3.Connection, AgentReadableMixin): |
| 62 | + """An agent-friendly wrapper around sqlite3.Connection.""" |
| 63 | +``` |
| 64 | + |
| 65 | +Guidelines: |
| 66 | + |
| 67 | +- Class docstring → "Purpose" section. Method docstrings → "Public API" summaries. |
| 68 | +- Override `__agent_notes__()` only for corner cases and anti-patterns. The mixin is not required for notes — Defining `__agent_notes__()` on any class (or monkey-patching it onto a third-party class) is enough; `agent_help()` collects it from the MRO automatically. |
| 69 | +- Add an "Agent usage" hint in the docstring — agents see it even via `help()`. |
| 70 | +- Simple data-only classes do not need agent docs. |
| 71 | + |
| 72 | +## Making a module agent-readable |
| 73 | + |
| 74 | +Modules are auto-documented — `agent_help()` generates docs from the module docstring and public members. |
| 75 | + |
| 76 | +**Do not override `__agent_help__` on a module unless absolutely necessary.** Unlike classes (which have `__agent_notes__()` to append guidance), overriding `__agent_help__` on a module replaces the auto-generated summary entirely — you lose signatures, purpose, and public API listing. Prefer writing clear docstrings on the module and its functions/classes instead. |
0 commit comments