From bc8184034f9b6290818214d03b2bbcaafe2cfbb0 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 7 Aug 2026 19:04:58 +0000
Subject: [PATCH] docs: suggest using pkg/logger for debug logs in AGENTS.md

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
---
 AGENTS.md | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 1b70a091bb3..080cc788897 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -107,6 +107,26 @@ DEBUG_COLORS=0 DEBUG=* gh aw compile workflow.md 2>debug.log
 
 To discover the exact namespace for a package, look for `logger.New(...)` at the top of the relevant `.go` file (e.g. `var log = logger.New("cli:run_workflow_execution")`).
 
+### Adding debug logs
+
+When adding new debug instrumentation to Go code, use `pkg/logger` — **never** `fmt.Println`, `log.Printf`, or other ad-hoc output:
+
+```go
+import "github.com/github/gh-aw/pkg/logger"
+
+var log = logger.New("cli:my_package") // one per file/package, at package scope
+
+func doSomething() {
+    log.Debug("starting operation", "key", value)
+    // ...
+    log.Debug("operation complete", "result", result)
+}
+```
+
+- Pick a namespace that matches the existing hierarchy (e.g. `cli:`, `workflow:`, `mcp:`).
+- Pass structured key/value pairs after the message for queryable context.
+- All output is gated by `DEBUG` at runtime — no user-visible noise in normal operation.
+
 ### GitHub Actions debug runs
 
 When `ACTIONS_RUNNER_DEBUG=true` is set (enabled automatically on re-run with debug logging in the GitHub UI), all loggers are activated — equivalent to `DEBUG=*`. No extra configuration is needed.