From a168946579afd7af6f7171500e09c440baa4a045 Mon Sep 17 00:00:00 2001
From: bneradt <bneradt@yahooinc.com>
Date: Thu, 25 Jun 2026 11:31:57 -0500
Subject: [PATCH] AI agent instruction updates

AI coding guidance does not fully reflect project conventions, which can
lead agents toward inconsistent names and less maintainable tests.

This aligns the instructions with established AuTest, Python, and C++
practices. It also documents both private-member prefix styles and the
community preference for `_` in new files.
---
 .github/copilot-instructions.md | 11 +++++++++--
 AGENTS.md                       | 24 +++++++++++++++++-------
 2 files changed, 26 insertions(+), 9 deletions(-)

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 72ed6387e1a..92e09afb98e 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -74,7 +74,11 @@ void function() {
 - Classes: `CamelCase` → `HttpSM`, `NetVConnection`, `CacheProcessor`
 - Functions/variables: `snake_case` → `handle_request()`, `server_port`, `cache_key`
 - Constants/macros: `UPPER_CASE` → `HTTP_STATUS_OK`, `MAX_BUFFER_SIZE`
-- Member variables: `snake_case` with no prefix → `connection_count`, `buffer_size`
+- Private member variables use both `_` and `m_` prefixes in the source code;
+  be consistent with the surrounding code. For new files, prefer the `_` prefix
+  because that reflects the community consensus.
+- Boolean variables and functions returning boolean values are named as
+  predicates: use `was_modified` rather than `modified`.
 
 **C++20 Patterns (Use These):**
 ```cpp
@@ -153,6 +157,7 @@ for (auto &conn : connections) {
 - Python 3.11+ with type hints
 - 4-space indentation (never tabs)
 - Type annotations on all function signatures
+- Use f'...' strings rather than .format() strings for new Python code.
 
 ### License Headers
 
@@ -358,7 +363,9 @@ plugins/my_plugin/
 **When adding new functionality:**
 1. Check if unit tests exist in same directory (Catch2)
 2. Add integration tests in `tests/gold_tests/` (autest)
-3. Prefer `Test.ATSReplayTest()` with `replay.yaml` format (Proxy Verifier)
+3. Prefer `Test.ATSReplayTest()` with `replay.yaml` format (Proxy Verifier). If
+   `ATSReplayTest` doesn't fit, prefer organizing the test around a test class with
+   separate functions for configuring the servers, ATS, client, etc.
 4. Test both success and error paths
 
 ## Configuration
diff --git a/AGENTS.md b/AGENTS.md
index e045c3c648f..d866f1845ff 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -123,12 +123,15 @@ regularly).
 using the Proxy Verifier format. This is simpler, more maintainable, and
 parseable by tools.
 
-**Python conventions for test and helper scripts:**
-- Launch Python helpers with `{sys.executable}` rather than a hardcoded `python3`,
-  so the test runs under the same interpreter the harness uses.
-- Prefer f-strings over `str.format()` when building command lines, config lines,
-  and `Testers` expressions.
-- Add type annotations to helper functions.
+If `ATSReplayTest` is not a good fit (say, the test needs a custom client), then
+organize the test around a test class with member functions that configure any
+servers, the ATS process, and the client. See
+`tests/gold_tests/ats_probe/ats_probe.test.py` for an example of a test organized
+around a test class.
+
+In autests, launch Python helpers with `{sys.executable}` rather than a
+hardcoded `python3`, so the test runs under the same interpreter the harness
+uses.
 
 **For complete details on writing autests, see:**
 - `doc/developer-guide/testing/autests.en.rst` - Comprehensive guide to autest
@@ -313,7 +316,11 @@ SMDebug(dbg_ctl, "Processing request for URL: %s", url);
 - CamelCase for classes: `HttpSM`, `NetVConnection`
 - snake_case for variables and functions: `server_entry`, `handle_api_return()`
 - UPPER_CASE for macros and constants: `HTTP_SM_SET_DEFAULT_HANDLER`
-- Private member variables have the `m_` prefix.
+- Private member variables use both `_` and `m_` prefixes in the source code;
+  be consistent with the surrounding code. For new files, prefer the `_` prefix
+  because that reflects the community consensus.
+- Boolean variables and functions returning boolean values are named as
+  predicates: use `was_modified` rather than `modified`.
 
 **Doxygen Comments:**
 
@@ -364,6 +371,9 @@ MIOBuffer *buffer = (MIOBuffer*)malloc(sizeof(MIOBuffer));
 ### Python Code Style (for tests and tools)
 - Python 3.11+ with proper type annotations
 - 4-space indentation, never TABs
+- Type annotations on all function signatures
+- Prefer f-strings over `str.format()` when building command lines, config lines,
+  and `Testers` expressions.
 
 ### Memory Management
 - Custom allocators supported (jemalloc, mimalloc)