Atlas Best Practices

3 min read

A map earns its keep when someone reaches for it during a release conversation. That takes less curation than people expect, and a different kind than they expect.

Build It in This Order

Sync. Your folders and requirements already encode real structure, and it is free and deterministic.
Discover from Canon. This fills in the parts of the product nobody filed a folder for — the screens, states and integrations your test organisation never named.
Curate. Rename, regroup, delete the noise. Your edits survive every later sync, so this work is not throwaway.
Link. A node with nothing linked contributes nothing to coverage or impact.
Draw journeys for the paths whose failure would stop a release.

Doing it in the other order — hand-drawing first — means throwing away work when sync produces a parallel tree.

Keep the Spine Shallow

Area → Module → Feature → Screen is the spine, and it is stable. Behaviours are leaves.

Do not nest for the sake of it. A five-level-deep hierarchy is a map nobody expands.
A behaviour that needs children is a feature. The map enforces this, and it is the right instinct.
Use Note for context that is not part of the structure, so it does not distort coverage roll-up.

Name Nodes for a Reader, Not a Folder

Sync names nodes after folders and requirements, which are often named for how a team works rather than what the product is. REG-2201 is a requirement id; Password reset is a part of the product.

Rename freely. Your renames are curated and sync will not undo them.

Draw Only the Routes That Matter

Every route is a claim, and a wrong claim makes impact analysis lie.

Worth drawing:

Dependency routes into shared services — auth, payment, notifications, anything several areas call
Navigation routes along your critical journeys
Routes across a system boundary, to an Integration node

Not worth drawing:

Every possible navigation in the product. The map becomes unreadable and impact analysis returns everything.
Routes that duplicate containment. A child is already related to its parent.

Name Journeys After Intent

Checkout is a feature. A returning customer buys with a saved card is a journey. The second one has a beginning, an end, and something that can be broken in the middle.

Mark the ones that genuinely stop a release as Critical — criticality is what lifts a test case into Must retest during impact analysis, so it is a working setting, not a label.

Re-sync on a Rhythm

Sync when structure changes, not on a timer:

After restructuring test folders
After a batch of requirements lands
Before a release review
When the orphan count on the Sync action goes up — those need a human decision

Permissions

Atlas has four permissions, configured per role. See Roles overview.

Permission	Allows
View	Open the map and trace coverage or impact back to it
Create	Add nodes and routes
Update	Re-sync the map and reshape it
Delete	Remove nodes, routes or the map itself

Reading is open to every project role, on the same argument Canon uses: a tester who cannot see the map cannot check the impact analysis or the coverage gaps they were handed from it.

Structural writes are restricted, because they change the map for everyone — Atlas is a shared artifact, not a personal view. Sync is an Update, not a Create, for exactly that reason.

Common Mistakes

Mistake	Why it hurts
Building the map by hand before syncing	Sync then produces a parallel tree you have to merge
Applying a whole Canon proposal without reviewing	Proposals vary run to run; unreviewed structure is noise
Never linking nodes to work	Coverage and impact both return nothing useful
Drawing every navigation route	Impact analysis returns most of the product
Deleting nodes to tidy up	Deletes are permanent against future syncs
Turning on Include tasks	The map fills with backlog items instead of product structure