用途：让编码智能体能够查询应用运行时行为。核心问题是智能体调试时往往无法回答“运行时到底发生了什么”，原因包括日志不存在或只是无结构的 console.log、日志存在但没有文档化的查询方式、智能体文档（CLAUDE.md、AGENTS.md）未说明如何访问遥测。
工作流程分五个阶段。阶段一审计现状：用 grep 查找日志基础设施（如 winston、pino、bunyan、log4j、slog、Logger、logging.config）、日志输出配置（LOG_LEVEL、LOG_FORMAT、LOG_FILE、OTEL_、SENTRY_DSN）、已有遥测端点（health、metrics、debug、status、readiness、liveness），并检查智能体文档是否提及日志访问；据此分类：无结构化日志进入阶段二，有日志但智能体无法访问进入阶段三，有日志和访问但未文档化进入阶段四，全部就绪则验证并建议改进。
阶段二添加结构化日志：使用结构化 JSON 而非字符串插值，包含关联 ID 用于请求追踪，在边界处记录（入站请求、出站调用、错误、状态转换），使用一致字段名（timestamp、level、message、requestId、userId、duration、error）。优先级为请求/响应中间件、错误处理器、外部服务调用、业务逻辑决策点。最小可行方案是请求日志中间件，记录 {timestamp, level, requestId, method, path, statusCode, duration, userId?}。
阶段三向智能体暴露日志，至少提供一种方式：选项 A 日志文件，写入已知路径供直接读取，如 tail -100 logs/app.json | jq 'select(.level == "error")'；选项 B 开发日志端点（Web 应用推荐），如 GET /__dev/logs?level=error&last=50，仅开发环境可用、返回 JSON 数组、支持按 level、path、timerange、requestId 过滤、限制响应大小（默认 100 条）；选项 C CLI 查询工具，如 ./scripts/query-logs.sh --level error --last 50。选择依据：Next.js/Express/Rails 本地开发用选项 B，CLI 工具或后台 worker 用选项 A，Docker 开发用选项 A 或 C，多服务 monorepo 用选项 C。
阶段四在智能体文档中记录，这是关键，否则智能体不知道遥测存在。在 CLAUDE.md 等文档中添加 Debugging 章节，包含可复制粘贴的命令、日志 schema、3-4 个常见调试工作流及确切命令、日志配置位置。
阶段五验证：触发请求、查询日志、验证智能体可用性（能否在 3 条命令内找到相关日志）、检查错误捕获。
反模式：console.log("here") 无结构无上下文；日志仅在云仪表盘导致智能体无法访问；全部 debug 级别过于嘈杂；记录敏感数据；无请求关联；文档只说“检查日志”而无具体方法。
限制：资料未提供具体框架实现代码、安装命令、收费或平台信息。