Skip to main content

Best practices

Keep main reviewable​

Use branches for meaningful changes, especially AI-generated changes. Merge only after reviewing additions, modifications, deletions, conflicts, and link proposals.

Use components consistently​

Components are the backbone for traceability and risk. Keep the component list short, stable, and product-oriented.

Good components:

  • Billing.
  • Authentication.
  • Search.
  • Notifications.

Weak components:

  • Sprint 19.
  • Misc.
  • Fixes.
  • Temporary.

Link test cases to requirements when tests are created. Waiting until release review makes traceability less useful and creates avoidable gate failures.

Preserve source provenance​

Add requirement sources for specs, customer asks, code references, and agent artifacts. Sources help reviewers understand why a requirement exists.

Align release strings​

Use the same release value everywhere:

  • CI release creation.
  • Runtime telemetry SDK.
  • Source map upload.
  • Quality gate checks.

Keep secrets separated​

  • API tokens belong in secret stores or ~/.tiden/config.json.
  • DSNs belong in app runtime config.
  • Workspace credentials belong in Tiden's credential vault.
  • Source map upload tokens belong only in CI.

Treat generated branches as proposals​

Do not merge agent output because it is generated. Inspect the source evidence, change diff, quality impact, and conflicts.

Use risk acceptance sparingly​

Risk acceptance is a business decision. Include a clear reason and approval when shipping with a soft failure.