From b994a076c28c148c07fa1212ac2fbe1a1be4cd3d Mon Sep 17 00:00:00 2001
From: Frank <97429702+tsubasakong@users.noreply.github.com>
Date: Sat, 7 Mar 2026 14:48:11 -0800
Subject: [PATCH] docs: add guidance for project documentation capture (#355)

---
 AGENTS.md               | 7 ++++++-
 examples/user-CLAUDE.md | 6 ++++++
 2 files changed, 12 insertions(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index ad250c43..52e96fab 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -92,7 +92,12 @@ Troubleshoot failures: check test isolation → verify mocks → fix implementat
 1. **Plan** — Use planner agent, identify dependencies and risks, break into phases
 2. **TDD** — Use tdd-guide agent, write tests first, implement, refactor
 3. **Review** — Use code-reviewer agent immediately, address CRITICAL/HIGH issues
-4. **Commit** — Conventional commits format, comprehensive PR summaries
+4. **Capture knowledge in the right place**
+   - Personal debugging notes, preferences, and temporary context → auto memory
+   - Team/project knowledge (architecture decisions, API changes, runbooks) → the project's existing docs structure
+   - If the current task already produces the relevant docs or code comments, do not duplicate the same information elsewhere
+   - If there is no obvious project doc location, ask before creating a new top-level file
+5. **Commit** — Conventional commits format, comprehensive PR summaries
 
 ## Git Workflow
 
diff --git a/examples/user-CLAUDE.md b/examples/user-CLAUDE.md
index 700e08e2..d7b774d5 100644
--- a/examples/user-CLAUDE.md
+++ b/examples/user-CLAUDE.md
@@ -79,6 +79,12 @@ Located in `~/.claude/agents/`:
 - 80% minimum coverage
 - Unit + integration + E2E for critical flows
 
+### Knowledge Capture
+- Personal debugging notes, preferences, and temporary context → auto memory
+- Team/project knowledge (architecture decisions, API changes, implementation runbooks) → follow the project's existing docs structure
+- If the current task already produces the relevant docs, comments, or examples, do not duplicate the same knowledge elsewhere
+- If there is no obvious project doc location, ask before creating a new top-level doc
+
 ---
 
 ## Editor Integration