diff --git a/AGENTS.md b/AGENTS.md index 92486a3..6c1606b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -213,6 +213,13 @@ Because CI is pinned, the rest of each range is not continuously verified: a new When deriving or changing a provider SDK window, record in the pull request the floor and ceiling the offline replay suite passes on, the failing test or `ImportError` behind each bound, and why the bound exists: a hard imported SDK symbol, test-level schema drift, or structural breakage that no test update can fix. Treat that evidence as a dated snapshot. SDK releases appear continuously, so re-derive any bound with the suite before changing it. `pyproject.toml` remains authoritative. +### Writing and Communication + +- Apply ASD-STE100 Simplified Technical English principles to all written output, including replies to the user, documentation, code comments, commit messages, PR titles and descriptions, and review comments. +- Write for understanding on the first read. Use familiar words, concrete and consistent terms, and simple sentence structures. Use code identifiers when they are more precise than a general description. +- Express one main idea per sentence. Prefer active voice and make conditions, actions, and consequences explicit. Present ideas in the order the reader needs to understand them. +- Include the information needed to understand the reasoning. Remove detail that distracts from it. Keep the text succinct without omitting necessary context or sacrificing technical accuracy. + ### Code Comments - Prefer clear code, meaningful names, and straightforward structure over comments that merely describe what the code does. @@ -225,10 +232,28 @@ When deriving or changing a provider SDK window, record in the pull request the - depends on subtle assumptions, ordering requirements, external behavior, or non-obvious invariants; - is sufficiently complex that its intent or correctness would otherwise be difficult to verify. -- Comments should explain **why** the implementation exists, what constraint or decision led to it, and, when useful, what could go wrong if it is changed. +- In general, state the problem or purpose first. Then briefly explain what must be done or how the solution resolves the issue. State the consequence of the problem or of violating the requirement. Use only as many sentences as needed to explain these points clearly. +- When wrapping comments, prefer line breaks at punctuation, such as sentence endings or commas. Keep related phrases together rather than filling each line to the maximum width. Respect the project's line-length limit. - Do not add comments that simply restate the code, narrate each operation, or compensate for unnecessarily complicated implementation. - Keep comments accurate when modifying the associated code. Remove comments that are obsolete, misleading, or no longer useful. +For example, "credential version" makes the reader infer which value matters and why. Name `refresh_counter` and explain the race and its consequence. + +Unclear: + +```python +# Keep the credential version that was authenticated under the account lock. +# Reloading it after commit could turn an old password into a new valid session. +``` + +Clearer: + +```python +# Guards against a login racing with a concurrent password reset. +# The session must retain the `refresh_counter` value read when its password was verified. +# Otherwise it may allow a session authenticated with the old password to survive the reset. +``` + ## Code Review and Refactoring Guidelines - Prioritize correctness, security, data integrity, and behavioral regressions.