docs: [IAC-4377] Update Best Practices with gotchas

[richardblack-Harness]

Description

• Update IaCM Best practices with gotchas and limitations
• JIRA

Screenshot / Preview

PRs must meet these requirements to be merged:

• Successful preview build.
• Code owner review.
• No merge conflicts.
• Release notes/new features docs: Feature/version released to at least one prod environment.

[Copilot]

Pull Request Overview

This PR updates the IaCM Best Practices documentation to add a new "Limitations & Gotchas" section and improves existing content with enhanced formatting, better linking, and clearer explanations.

• Adds a dedicated "Limitations & Gotchas" section highlighting important constraints and considerations
• Enhances documentation with better internal linking and formatting improvements
• Updates link references to use relative paths instead of full developer.harness.io URLs

Comments suppressed due to low confidence (2)

docs/infra-as-code-management/iacm-best-practices.md:60

• The relative link docs/code-repository/ is missing the leading slash. It should be /docs/code-repository/ to match the pattern used in other links in this file and ensure proper navigation.

Harness seamlessly integrates with third-party services like external code repositories and secret managers, providing flexibility in tool choice. However, using Harness’s native services like [Harness Code Repository](docs/code-repository/) and [Harness Secret Manager](docs/platform/secrets/secrets-management/harness-secret-manager-overview/) can offer key performance and operational benefits.

docs/infra-as-code-management/iacm-best-practices.md:60

• The relative link docs/platform/secrets/secrets-management/harness-secret-manager-overview/ is missing the leading slash. It should be /docs/platform/secrets/secrets-management/harness-secret-manager-overview/ to match the pattern used in other links in this file and ensure proper navigation.

Harness seamlessly integrates with third-party services like external code repositories and secret managers, providing flexibility in tool choice. However, using Harness’s native services like [Harness Code Repository](docs/code-repository/) and [Harness Secret Manager](docs/platform/secrets/secrets-management/harness-secret-manager-overview/) can offer key performance and operational benefits.

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[bot-gitexp-user]

Please check the Execution Link of the Pipeline for the Website Draft URL. This is located in the Preview Step behind the Harness VPN and also is available in #hdh_alerts. E.g Website Draft URL: https://unique-id--harness-developer.netlify.app. Current Draft URL is: https://68ad8d23d648826d0721dca8--harness-developer.netlify.app