From 07d4527a0d3d703cda1f93230886a3718a786e89 Mon Sep 17 00:00:00 2001
From: jinliyl <6469360+jinliyl@users.noreply.github.com>
Date: Mon, 13 Jul 2026 23:05:35 +0800
Subject: [PATCH] docs(agents): update coding conventions for state persistence
 (#342)

- Add guideline that steps should be stateless
- Specify storing persistent state in self.app_context.metadata
- Clarify avoiding state storage on step instances
---
 AGENTS.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 25675fa7..e5990bef 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -112,6 +112,8 @@ authorized the necessary environment.
 ## Coding and Test Conventions
 
 - Target Python 3.11+ and follow the surrounding typing and async style.
+- Steps are stateless. If a step needs to persist state, store it in
+  `self.app_context.metadata` rather than on the step instance.
 - Keep public schemas explicit and backward-compatible where practical.
 - Close async clients, services, tasks, and other lifecycle resources deterministically.
 - Prefer clear failures over silently falling back to corrupt or ambiguous state.