Mark H

VP of Engineering

Atono is the product engineering platform that keeps product context connected to the work.

Product Plan Icon

Product Plan Icon White

Box Build icon

Product Build Icon

Product Deploy Run Icon

Product Deploy Run Icon White

Measure Linegraph Icon Blue

Measure Linegraph Icon White

Story Assistant

AI Product Development   It's an Authoring Problem, Not a Review Problem

Atono Logo

Check your email to get started. Don&rsquo;t see it? Be sure to check your spam folder.

LinkedIn Social Icon

LinkedIn Social Icon Blue 500

YouTube Social Icon

YouTube Social Icon Blue 500

Substack Social Icon

Substack Social Icon Blue 500

Claude.md Blog Image

CLAUDE.md breaks for teams because it's a hand-maintained private file with no shared ownership &ndash; so it drifts, fragments, and quietly stops being true the moment more than one engineer or AI agent depends on it.
A CLAUDE.md file works well for an individual engineer, and it can work for a small team. The cracks start to show once that context has to stay consistent across more people, more repos, and the agents now working alongside them &ndash; because the file is hand-maintained scaffolding that nobody else owns and nothing keeps current.
The file isn't the problem. The pattern is: product context kept as a private document instead of a shared system.

A CLAUDE.md (or a .cursorrules file, a system prompt, a folder of prompt snippets) is a local cache of product context. You write down the terms and gotchas an agent keeps getting wrong, and it reads them on each run. For solo work that's perfect &ndash; it lives in your head as much as in the file, and it changes when you do.
This is the core of CLAUDE.md best practices for individuals: a lightweight, personal context file that keeps your AI coding agent on track for your specific repo and workflow. Cursor rules for teams hit the same wall, just with a different filename.
That local-cache quality is exactly why it doesn't generalize.

The first crack is drift. Your CLAUDE.md describes the product as you understood it the last time you touched the file. The product moved; the file didn't. So the agent confidently applies a rule that stopped being true two sprints ago &ndash; the file still says an "active user" is anyone who logged in this month, six weeks after the team redefined it &ndash; and the output comes back almost right, which is worse than wrong because it passes a skim and ships.
I'll admit I learned this the hard way: I kept my own CLAUDE.md for months and watched it quietly rot. Every entry was true the day I wrote it, and half of them were wrong by the time anyone else relied on them.
The second crack is fan-out. Five engineers means five CLAUDE.md files, each a little different, none reconciled. The claude code context one person's agent runs knows things another's doesn't, with no shared version and no review. Add agents that hand work to each other, and each is operating from a different, partial picture of the same product &ndash; so the coordination failures that follow are easy to blame on the model, though the gap is usually AI agent context: each agent is working from an incomplete and inconsistent view of the product.
This is the common case, not the edge case. In the <a href="/lp/context-gap-report">Context Gap Report</a>, 52% of teams have no shared AI coding agent context &ndash; each developer manages their own prompts and files &ndash; and that climbs above 75% at organizations with 500&ndash;1,000 engineers. 54% of engineers say most AI quality issues are actually context issues.

The usual next move is to make one shared CLAUDE.md for the whole team. That helps consistency, but it doesn't fix ownership. The file still competes for attention with code reviews, sprint work, doc updates, and roadmap changes, and it still needs an owner &ndash; someone to keep it current and police what belongs in it, across every tool that's supposed to use it.
The fix isn't a better place to keep the file. It's treating product context as a system instead of a document &ndash; and that's the part a shared file can't give you, no matter how disciplined the team is.

What scales is structured product context that lives outside any one person's repo: the terminology, decisions, and rules held once, maintained as part of the work, and read by every tool and agent from one shared system – usually delivered as <a href="/blog/introducing-atonos-mcp-server">MCP server context</a> any compatible client can pull. Think of it as <a href="/learning/what-is-ai-context">durable agent memory maintained through shared workflows,</a> rather than scattered across personal files that depend on each engineer remembering to update them.Engineers stop re-explaining the product to their tools, and the hours that went into babysitting a private file go back into building.A CLAUDE.md is a cache. Product Knowledge is the shared understanding for what your product means. Teams scale when every engineer and every agent reads from the same shared understanding instead of maintaining private caches.

<h3>Is CLAUDE.md bad?</h3>No. It's a good, lightweight tool for a single engineer on a single repo. The limitation is structural – it has no built-in way to stay current or be shared once more than one person depends on it.<h3>What are CLAUDE.md best practices for teams?</h3>For individual engineers, CLAUDE.md best practices mean keeping the file focused, up to date, and scoped to your repo. For teams, the better practice is to use a thin local CLAUDE.md for personal preferences while pulling shared product context from a governed MCP server – so the product-correctness part is maintained once, for everyone, rather than duplicated across files that each drift independently.<h3>Why does CLAUDE.md drift?</h3>Because it's hand-maintained and separate from the product. The product changes during normal work; the file only changes when someone remembers to edit it, so it gradually describes a product that no longer exists.<h3>Should every repository have a CLAUDE.md?</h3>Many teams keep a lightweight CLAUDE.md for repository-specific guidance, and that's a reasonable approach. The mistake is treating it as the primary source of product context. Local files work best when they consume shared context rather than replace it.<h3>What's the alternative for a team?</h3>Structured product context served through an MCP server, so every engineer and every agent reads the same current context instead of maintaining private copies. The <a href="/product-glossary">Product Glossary</a> holds terminology; <a href="/blog/living-stories-in-action">AI Context holds the decisions and history</a> behind each piece of work.<h3>Can CLAUDE.md replace a project management tool like Jira or Linear?</h3>No – they solve different problems. <a href="/comparison/jira">Jira</a>, <a href="/comparison/linear">Linear</a>, and <a href="/comparison/shortcut">Shortcut</a> manage tasks, sprints, and delivery workflows. CLAUDE.md (and its replacement, structured product context) manages the product context your AI coding agents need to understand what they're building, not what needs to be built. Teams using both still need their project tool; what they gain is agents that stop getting the product wrong.<h3>Can I keep my CLAUDE.md and use Product Knowledge too?</h3>Yes. Many teams keep a thin local file for personal preferences and let the shared, governed context come from the MCP server, so the product-correctness part is maintained once for everyone.

Shared context from first decision to feature usage

Eng Lead Blog Featured Img V2

Engineering managers don&rsquo;t just manage code&mdash;<a href="/blog/why-ai-tools-create-coordination-chaos">they manage chaos.</a>
Shifting priorities mid-sprint. Critical bugs across teams. Stakeholders needing delivery answers now. In the middle of it all, you&rsquo;re trying to keep the team focused, the backlog healthy, and the release on track.
Atono is designed to support that balancing act. It gives engineering leads the visibility to see what's happening, the control to adjust course, and the peace of mind that nothing critical is slipping through the cracks. It doesn&rsquo;t replace your team&rsquo;s process&mdash;it strengthens it.

The team backlog &mdash; <a href="https://docs.atono.io/update/docs/scrum-backlog" target="_blank" rel="noopener">Scrum</a> or <a href="https://docs.atono.io/update/docs/kanban-backlog" target="_blank" rel="noopener">Kanban</a> is where managers stay on top of a team&rsquo;s day-to-day work. Use it to review upcoming stories, prioritize testing tasks, track bugs, and prepare for story sizing and review.
Filters make it easy to focus on what matters&mdash;by item type, assignee, product theme, timebox, or when something was created or last updated. Whether you're reviewing what&rsquo;s ready to size, checking on recent updates, or reviewing a sprint, the filters help you get there quickly.
<img src="https://atono-test.directus.app/assets/2df2d054-9710-4d20-a4bc-1205aa2453b0.jpg?width=2952&amp;height=1484" alt="Team Backlog">
It&rsquo;s also a helpful space for syncing with product and design&mdash;walking through stories, aligning on scope, and making sure everyone&rsquo;s clear on priorities. <a href="/solutions/engineering-managers">Engineering managers</a> also use the backlog to coordinate test planning with QA&mdash;helping surface what&rsquo;s coming next and align on priorities before release.
<a href="/tutorials/advanced-set-up-and-customization/team-backlog-owners">Every team has its own backlog in Atono,</a> so the view stays focused and relevant&mdash;no cross-team clutter. The result is a clean, purposeful workflow that keeps the team moving forward.

In the middle of a review or planning session, it&rsquo;s common to need clarity on what exactly is being built. <a href="/blog/living-stories-in-action">Atono&rsquo;s stories give you just that.</a> Each story includes a structured user story, acceptance criteria, comments, and links to related items&mdash;all in one place.
If something isn&rsquo;t clear, you can link directly to a specific AC to ask a question or request a change. Comments keep those conversations anchored to the story, so you don&rsquo;t lose context across tools.
Managers also use linked items to check dependencies, see related bugs, and track defects they&rsquo;ve uncovered through testing. And when it&rsquo;s time for review, the story view makes it easy to validate what was delivered against what was expected.
<img src="https://atono-test.directus.app/assets/4a305e9b-9a7e-443a-9764-fef8d3c89a77.jpg?width=2532&amp;height=1382" alt="a story with comments, linked items, copying an AC link">

Let teams work differently without losing delivery visibility.

While the team backlog keeps your focus on day-to-day execution, the <a href="https://docs.atono.io/docs/everything" target="_blank" rel="noopener">Everything page </a>helps you go broader&mdash;and deeper. It brings together stories and bugs across your organization, including the ones your team owns, so you can see how work fits into the bigger picture or investigate details that aren&rsquo;t visible in the backlog.
Unlike the backlog, which is scoped to a single team, the Everything page offers advanced filters across item types, statuses, themes, timeboxes, and more. Managers use it to check the status of cross-team deliverables, prepare for reviews, or share recently closed work with QA to support regression test planning.
It&rsquo;s also a fast way to find specific issues, check for duplicates, or validate whether a bug has already been filed&mdash;without hopping through multiple tools. You can save filtered views to quickly return to high-priority sets of work without resetting filters every time.
<img src="https://atono-test.directus.app/assets/122f9e6b-566c-447f-9552-a7f034674ee2.jpg?width=2892&amp;height=1476" alt="Everything page with Save as new view option">

The <a href="https://docs.atono.io/docs/bug-triage" target="_blank" rel="noopener">Bug triage page</a> gives engineering managers a focused space to review and act on reported issues&mdash;without distracting from day-to-day delivery. You can assess severity, reject low-quality reports, or ask for more information before anything reaches your team&rsquo;s backlog.
Each bug includes key context: whether it&rsquo;s linked to a story, a risk rating based on impact and probability, and any follow-up comments. You can link to acceptance criteria, start a conversation to clarify the issue, or route it to the right team when you're ready. Once prioritized, you can add bugs directly to a team&rsquo;s backlog.
The triage page surfaces reported bugs across your organization, so you can catch issues early&mdash;even if they haven&rsquo;t been assigned yet. By separating triage from the main backlog, Atono helps you reduce noise, improve prioritization, and ensure that only well-understood, actionable bugs make it to the team. That means fewer distractions, higher-quality bug reports, and cleaner handoffs to engineering.
<img src="https://atono-test.directus.app/assets/9397a255-73f3-4d3b-bbe7-768690dc167e.jpg?width=2892&amp;height=1480" alt="Bug Triage">

Atono <a href="/blog/how-atonos-feature-flags-empower-fast-development">feature flags support coordinated rollouts</a> across dev, test, and production. Feature flags can be added to one or more stories, giving everyone clear visibility into what functionality is controlled by a flag&mdash;and what&rsquo;s live in which environments.
Flags give engineering managers more control over how and when features are released. You can test in isolation, control rollout by environment, and release incrementally&mdash;without relying on <a href="/blog/real-cost-of-separate-feature-flag-tools">long-lived branches</a> or risky deployments. It&rsquo;s especially helpful for testing and validation workflows that need flexibility without overhead.
To support ongoing maintenance, Atono tracks when each flag was last evaluated in your codebase. That makes it easier to spot flags that are still actively used versus those that can be safely cleaned up.
Because flags are visible in the story, product, QA, and engineering stay aligned on what&rsquo;s being tested, released, or held for later&mdash;reducing surprises and smoothing handoffs across teams.
<img src="https://atono-test.directus.app/assets/2d8d21be-895a-42d8-be64-1886b8477970.jpg?width=2894&amp;height=1458" alt="Feature Flags">

Atono automatically tracks how long work spends in each step of your team&rsquo;s workflow, giving you a detailed, step-specific view of your cycle time. The <a href="https://docs.atono.io/docs/cycle-time#cycle-time-report">Cycle time report</a> breaks this down by workflow step and story size (if used), so you can pinpoint exactly where work tends to slow down, evaluate whether changes to your process are making a difference, and explain delivery patterns when questions arise.
<img src="https://atono-test.directus.app/assets/c1431cca-ca5a-4fdf-b037-e4b11e954930.jpg?width=2434&amp;height=1202" alt="Cycle Time Report">
Paired with story sizing, cycle time data helps managers validate estimates and understand team velocity. When stories or bugs take longer than expected in a particular step, Atono flags them with a red <a href="https://docs.atono.io/docs/staleness-indicator">staleness indicator</a>&mdash;based on your team&rsquo;s own historical data, not arbitrary thresholds. You can exclude known outliers to keep your data clean and insights accurate.
Atono also shows <a href="https://docs.atono.io/docs/estimated-completion-dates">estimated completion dates</a> when enough history is available, giving you an informed view of what&rsquo;s likely to ship and when.
If you want to keep these insights front and center, you can create saved views that highlight high-risk or aging work&mdash;like bugs stuck in triage or stories waiting on review. It&rsquo;s a simple way to spot blockers before they become delays.
<img src="https://atono-test.directus.app/assets/2b9d8be0-57f2-459b-9b7c-ffa2f7158cbd.jpg?width=2852&amp;height=1476" alt="Saved View Widgets">

Atono&rsquo;s <a href="https://docs.atono.io/docs/timelines">timelines</a> help engineering managers communicate what&rsquo;s planned, what&rsquo;s been delivered, and when upcoming work is expected to land. You can group stories and bugs into timeboxes and arrange them visually for different audiences&mdash;no spreadsheets required.
<img src="https://atono-test.directus.app/assets/978e49fc-4ad2-4bfe-9055-8ee0dfcabc6c.jpg?width=2458&amp;height=1378" alt="Timeline">
Timelines stay up to date as your plans evolve. You can resize timeboxes as needed or keep dates fixed and adjust scope within them&mdash;Atono supports both approaches, so you can plan the way that works best for your team.
To make sure those timelines are realistic&mdash;not just optimistic&mdash;you can use cycle time trends and estimated completion dates to validate what&rsquo;s feasible. These data points are based on your team&rsquo;s actual delivery history, not wishful thinking.
As work progresses, the stories and bugs in each timebox reflect their current state&mdash;whether they&rsquo;ve been completed, delayed, or changed in scope. That gives you a clear view of how delivery is tracking without needing to manually update a roadmap.

Atono gives engineering managers the tools to lead with less stress and more certainty. Whether you're juggling shifting priorities, cross-team dependencies, or last-minute delivery questions, <a href="/product">Atono keeps you anchored in the details that matter.</a>
It brings clarity to the messy, fast-moving reality of software development&mdash;so you can lead with confidence, not chaos.
With one system designed for the way modern teams actually work, you can focus less on wrangling tools and more on keeping your team effective.

Solutions

Resources

Mark H

VP of Engineering

Articles by Mark H

Why Claude.md doesn't scale

How Atono gives engineering leads more visibility, control, and peace of mind