Update agent documentations to avoid unnecessary code comments (#4115)

* Update agent documentations to avoid unnecessary code comments

* Fix broken docs link

Author: strickvl

.cursor/rules/comments.mdc

@@ -0,0 +1,30 @@
+---
+description: Project-wide commenting policy — explain WHY the code is the way it is; avoid change-log comments.
+alwaysApply: true
+---
+
+# Commenting Policy: Explain **Why**, Not **What**
+
+**Goal:** Comments should help a future maintainer understand intent and constraints months later—not narrate edits.
+
+## Use comments to explain
+- Non-obvious design decisions / trade-offs and invariants
+- Complex logic or algorithms (what makes them tricky)
+- Business rules and constraints that drive the design
+- Purpose and contract of functions/classes (especially public APIs)
+- Edge cases and gotchas being handled and why they matter
+
+## Avoid change-tracking comments
+- “Updated from previous version”
+- “New implementation”
+- “Changed to use X instead of Y”
+- “Refactored this section”
+
+## Avoid simple explanatory comments
+- Avoid comments that are obvious descriptions of what the code does when it's
+  already clear from the code itself.
+
+## Guidance
+- Prefer self-explanatory code; add comments only where extra context is genuinely needed.
+- Write for “future you” 6+ months from now.
+- In Python, prefer docstrings for API intent and inline comments only for truly non-obvious lines.

AGENTS.md

@@ -14,6 +14,12 @@ Use filesystem navigation tools to explore the codebase structure as needed.
 
 ## Code Style & Quality Standards
 
+### Commenting policy — explain why, not what
+- Use comments to document intent, trade‑offs, constraints, invariants, and tricky edge cases—i.e., why the code is this way—rather than narrating changes. Prefer self‑explanatory code; add comments only where extra context is needed. Write for a reader 6+ months later.
+- Use for: complex logic/algorithms, non‑obvious design decisions, business rules/constraints, API purpose/contracts, edge cases.
+- Avoid: change‑tracking comments (“Updated from previous version”, “New implementation”, “Changed to use X instead of Y”, “Refactored this section”).
+- Avoid simple explanatory comments, where it is already clear from the code itself.
+
 ### Formatting and Linting
 - Format code with: `bash scripts/format.sh` (requires Python environment with dev dependencies)
   - Run this before every commit to ensure proper formatting

CLAUDE.md

@@ -24,6 +24,12 @@ Note: The MCP server indexes the latest released docs, not the develop branch. F
 
 ## Code Style & Quality Standards
 
+### Commenting policy — explain why, not what
+- Use comments to document intent, trade‑offs, constraints, invariants, and tricky edge cases—i.e., why the code is this way—rather than narrating changes. Prefer self‑explanatory code; add comments only where extra context is needed. Write for a reader 6+ months later.
+- Use for: complex logic/algorithms, non‑obvious design decisions, business rules/constraints, API purpose/contracts, edge cases.
+- Avoid: change‑tracking comments (“Updated from previous version”, “New implementation”, “Changed to use X instead of Y”, “Refactored this section”).
+- Avoid simple explanatory comments, where it is already clear from the code itself.
+
 ### Formatting and Linting
 - Format code with: `bash scripts/format.sh` (requires Python environment with dev dependencies)
   - Run this before every commit to ensure proper formatting
@@ -297,4 +303,4 @@ When tackling complex tasks:
 ---
 
 *This document is maintained to help Claude Code work effectively with the
-ZenML codebase. For human contributors, see CONTRIBUTING.md.*
+ZenML codebase. For human contributors, see CONTRIBUTING.md.*

docs/book/getting-started/zenml-pro/secrets-stores.md

@@ -17,7 +17,7 @@ This operation has two main stages:
 
 ## AWS Secrets Manager
 
-The authentication used by the AWS secrets store is built on the [ZenML Service Connector](https://docs.zenml.io/stacks/service-connectors/overview) of the same type as the secrets store. This means that you can use any of the [authentication methods supported by the Service Connector](https://docs.zenml.io/stacks/service-connectors/connector-types/aws-service-connector#authentication-methods) to authenticate with the secrets store.
+The authentication used by the AWS secrets store is built on the [ZenML Service Connector](https://docs.zenml.io/stacks/service-connectors/auth-management) of the same type as the secrets store. This means that you can use any of the [authentication methods supported by the Service Connector](https://docs.zenml.io/stacks/service-connectors/connector-types/aws-service-connector#authentication-methods) to authenticate with the secrets store.
 
 The recommended authentication method documented here is to use the [implicit authentication method](https://docs.zenml.io/stacks/service-connectors/connector-types/aws-service-connector#implicit-authentication), because this doesn't need any sensitive credentials to be exchanged with the ZenML Pro support team.
 
@@ -236,4 +236,4 @@ After your workspace is updated, you will see the following changes in the works
     }
   }
 }
-```
+```