DEV Community: Edensoft Labs

Debunking the AI Documentation Myth: What Engineering Leaders Must Know

Andrew Park — Thu, 11 Jun 2026 01:13:04 +0000

Throughout my career, I’ve had conversations with many Engineering VPs and CTOs who’ve shared a common frustration: “Our developers have never been great at documentation, and it’s leads to a lot of technical debt problems.” But there’s a new twist now. Over the last year I’ve heard some of these same leaders placing hope in AI tools to solve this once and for all. This is a seductive belief, and it’s also one of the most dangerous myths in modern software development.

Two specific assertions keep coming up, which can be summarized by these quotes:

“AI tools can now generate documentation for every function, class, and file. Our codebase looks well-documented now, so the problem has been solved.”

“AI can just ingest the entire codebase and answer any question about it, so even if our documentation is lacking, we’re covered.”

Unfortunately, both of these assumptions fall apart under scrutiny. AI tools aren’t a solution to a lack of documentation discipline, they are an amplifier. They take your current documentation culture and amplify it. If you’ve trained your engineers to think clearly and document well as I have, AI can save them lots of time. But if those habits aren’t in place, AI simply helps you create more poorly documented code than ever, at greater speed and amplification. The core challenge is not a lack of tools, but a lack of human skill, and AI makes cultivating that human skill more critical than ever. The primary takeaway is that human skill must be cultivated to address 7 key areas where AI is fundamentally limited, and doing so will result in a more effective development process for both humans and AI.

What AI Tools Can and Can’t Do

AI coding assistants like Copilot, Cursor, and CodeRabbit have made it easier than ever to generate documentation with minimal effort. They can autocomplete docstrings, summarize pull requests, and describe functions in grammatically correct prose. But when you step back and judge them by what really matters for long-term maintainability, things like conceptual integrity, architectural clarity, and preserved business intent, the picture changes. The table below ranks nine documentation-related capabilities by their importance to system maintainability, and evaluates how well each tool supports them.

The table makes it undeniably clear. AI tools address the low-hanging fruit very well. But that success has led many engineering VPs and CTOs to believe the documentation problem is solved. What they see looks impressive. Every file, class, and method is now wrapped in clean, well-formatted comments generated by AI. But most of that content is superficial boilerplate. It brings value in that it saves developers time, many can just make a few edits instead of writing from scratch. But the deeper gaps, the ones that impact maintainability the most, aren’t being touched because they require human expertise. AI doesn’t capture intent. It doesn’t explain architectural reasoning. It doesn’t preserve tradeoffs, product constraints, or regulatory context. That’s still entirely on the human developer. And now that AI amplifies their output, a developer’s understanding of how to document well has never been more important. If that human skill is missing, you don’t get better documentation. You just get two or three times more poorly documented code than before. Only now it looks polished enough to fool engineering management that they've plugged the documentation gap.

Priority 1. Maintaining Conceptual Integrity

Fred Brooks introduced the idea of conceptual integrity in software design, and it stuck with me early in my career. I baked it into the engineering culture of every product team I’ve led. Why? Because once a system loses its conceptual integrity, innovation speed slows to a crawl. And once architectural technical debt leads to incoherent structure, it’s game over. You’re facing two options: rewrite the codebase from scratch or sunset the product.

AI tools aren’t equipped to help here. They don’t enforce consistent abstractions. They don’t preserve mental models. They don’t notice when naming conventions drift or when layers blur together. And because AI learns from the patterns it sees in your codebase, it breaks down when the codebase has no clear patterns. Incoherent codebases don’t just confuse people, they confuse AI too.

AI can be prompted to follow clean abstractions and consistent naming, but that only works if a strong architectural foundation already exists. It takes well-trained engineers to establish that clarity in the first place. In other words, the usefulness of AI depends on the design coherence it’s exposed to. When the codebase is clean and well-structured, AI can become a helpful pattern follower. But when the structure is weak or inconsistent, AI just amplifies the mess.

This is a problem of human architectural thinking, and AI can’t solve a conceptual problem that the human developers themselves haven’t addressed. The human must provide the conceptual map for both other humans and the AI to follow.

We’ve seen the same pattern when using AI to answer questions about the code or summarize logic. The quality of the results improves dramatically when developers take the time to refactor variable names and apply clear, consistent naming. Vague variable names like temp, data1, value, result, or loop counters like i, j, and k confuse AI just as much as they confuse people. The same is true for non-standard or team-specific acronyms. Especially ones that aren’t documented or recognized beyond the immediate team. AI lacks the shared context to interpret them accurately. But when variable names reflect real domain concepts and acronyms are either standardized or spelled out, AI becomes significantly more helpful.

In this way, good naming and coherent design aren’t just about human readability… they’re force multipliers for AI effectiveness. But that foundation must be laid by skilled human engineers.

Priority 2. Understanding Intent and Business Context

Great documentation doesn’t just explain what the code does. It explains why it exists. It captures the intent behind decisions, the business priorities that shaped them, and the tradeoffs that were consciously made. This is the kind of context that makes a system understandable, not just executable.

AI tools don’t have access to that layer of reasoning because they operate solely on observable artifacts like code, comments, commit messages, and sometimes surrounding files. But the real “why” behind the code lives in conversations, meetings, design reviews, customer feedback sessions, and compliance decisions. None of that is visible to AI unless it’s deliberately and thoroughly documented.

Even when that context is written down, it’s rarely structured in a way AI can reliably interpret. Meeting notes are ambiguous. Jira tickets are inconsistent. Slack threads are noisy and full of contradictions. AI may ingest all of it, but it doesn’t know which parts are authoritative, which reflect final decisions, or which ideas were discarded. It lacks the judgment to separate signal from noise. That’s why its outputs often sound polished but fail to reflect the actual thinking behind the system.

Feeding it more context might produce results that sound convincing but still miss the mark. AI doesn’t reason about intent. It matches patterns based on what was written, not what was meant. When the inputs are messy, incomplete, or out of date, the outputs become misleading—or even dangerous to rely on.

That deeper context often goes undocumented, and AI can’t discover it on its own. When that context is missing, the consequences are predictable:

Developers waste time reverse engineering past decisions
Teams revisit tradeoffs that were already resolved
Systems drift away from original goals or compliance boundaries
AI tools generate confident but incorrect explanations
Critical code gets removed because no one remembers why it existed

Some of my senior engineers have experimented with injecting architectural context, product constraints, or regulatory considerations directly into AI prompts. In isolated cases, that’s led to better results. But those improvements are fragile and hard to repeat. For example, a carefully crafted prompt might work well when applied to a single file, but when you try to scale that same approach across dozens or hundreds of files, the quality of AI responses usually breaks down and becomes counterproductive. The approach doesn’t scale, and it doesn’t change the fundamental limitation. AI can’t infer intent, rationale, or tradeoffs unless they’re clearly and explicitly written. It can only reflect the clarity and completeness of the input it’s given.

Since 2004, I’ve focused on building teams of product engineers rather than teams of traditional software engineers. That shift started by changing how we think about documentation. We made it standard practice to embed intent and business context directly into the source code, making sure every engineer understood not just how the system worked, but why it was built that way.

This dramatically increased the value our engineers provided to product managers. It helped close the gap between product and engineering by embedding product knowledge into the development process. If you want engineers who think like missionaries instead of mercenaries, this is where it starts.

AI can’t teach this mindset. But a product oriented software engineering culture can.

Priority 3. Linking Code to Broader Architecture

AI tools like Cursor and CodeRabbit offer features that seem to promise architectural insight. Cursor can generate Mermaid diagrams that show class hierarchies, function calls, and file dependencies. CodeRabbit’s “Code Graph Analysis” maps how different parts of the codebase interact. These tools can be useful for getting a quick sense of structure, especially when onboarding new developers.

But here’s the problem: the structural relationships these tools show don’t reveal architectural reasoning. They tell you how code is connected but not why it’s structured that way. They don’t explain what design tradeoffs were made, what constraints the architecture is trying to satisfy, or how the system supports product-level goals.

Architectural documentation needs to clearly reveal intent. It should answer questions like why a module exists, what problem it solves, how it enforces boundaries, and how it supports things like scalability, compliance, or product strategy. That kind of reasoning doesn’t live in the code itself. It comes from design reviews, whiteboard sessions, strategic discussions, and conversations with product and architecture leaders. AI tools don’t have access to any of that.

So while AI can draw the wiring diagram, it has no idea what the system is supposed to look like. It won’t notice when a change violates key abstractions or weakens the architectural boundary between layers. Without a strong architectural foundation created and maintained by humans, AI just reflects the current state of the system, whether it’s clean or a god awful mess, and makes it look polished.

If you want documentation that supports long term maintainability and safe evolution of the codebase, your engineers need to be sufficiently trained to write and think at the architectural level. Once that foundation is in place, AI can help visualize and reinforce it. But it can’t define it. It can’t explain it. And it definitely can’t create it for you.

Priority 4. Documenting Evolving Systems

A major challenge in documentation is keeping it accurate as the codebase evolves. Outdated documentation can be worse than none at all because it misleads developers and introduces bugs.

AI tools might seem like a solution here, but they’re fundamentally reactive. They generate documentation on demand or when triggered by something like a pull request. But they don’t have a persistent, holistic view of the system. They don’t know if a change contradicts earlier architectural decisions or if new documentation subtly conflicts with what’s already written elsewhere. They don’t understand the broader system well enough to make that call.

It’s true that with the right prompt, an AI tool can check whether a function’s documentation matches its implementation. That kind of localized accuracy check can be useful. But it doesn’t scale. AI still can’t understand the full context of a large, complex codebase. It can’t trace architectural intent across dozens or hundreds of files. It doesn’t carry forward assumptions made months or years ago. It doesn’t understand which patterns are deliberate and which are accidental. That lack of global awareness is a fundamental limitation. Right now, AI can assist at the micro level, but fails at the macro level.

This limitation won’t be solved just by giving AI a larger context window. It’s a classic garbage in, garbage out problem, well known in data science and now just as relevant in AI generated documentation. No matter how many files or tokens a model can ingest, it’s still fundamentally dependent on the quality of the inputs. If the codebase is conceptually incoherent, structurally weak, and missing documentation, the AI will reflect those flaws, not repair them. You’ll get longer summaries as it attempts to make sense of incoherent architecture, more confident hallucinations about undocumented logic, and more elaborate diagrams that yet fail to deliver real insights. Increasing the context window doesn’t help if the inputs themselves are noisy, inconsistent, or lacking the context that makes them interpretable.

That’s why human leadership and discipline are more important than ever. Engineering leaders need to build a culture where documentation is a living and evolving part of the system, not a one-time artifact generated by a tool. Developers need to be trained to recognize when a change impacts previous assumptions or shifts architectural boundaries, and they need to feel responsible for keeping documentation accurate when that happens.

AI can speed up the grunt work. It can draft summaries, format docstrings, and flag surface-level inconsistencies. But without skilled engineers applying judgment, context, and historical awareness, the kind of meaningful, system-wide documentation that makes complex software maintainable won’t happen. AI helps you move faster, but only humans can make sure you’re documenting all the things that matter as the system evolves.

Priority 5. Ethical or Regulatory Considerations

Software systems often include logic shaped by legal requirements, ethical principles, and industry-specific regulations. In healthcare, this might mean HIPAA. In finance, it could involve SOX. In defense, it includes STIGs, CUI handling, and other classified or export-controlled standards. Documenting these constraints isn’t optional; it’s essential for avoiding legal, financial, and national security risks.

Even when tools like Cursor let you attach compliance files, the AI still doesn’t truly understand what those documents mean. You can feed an AI model a compliance handbook or a DoD instruction and prompt it to follow those standards when writing or reviewing code, but two big limitations still remain:

AI can’t tell what’s relevant or authoritative. It doesn’t know whether a regulation is outdated, conditional, organization-specific, or has been replaced. It lacks the judgment to interpret complex rules the way a trained human can.
AI can’t be held accountable. It might generate confident explanations, but it won’t take responsibility when something goes wrong (e.g., failed audit, compliance breach, compromised system).

Even if you give AI all the right context, it’s still on the human developer to understand the rules, apply them properly, and clearly document why certain decisions were made. Without that, you’ll end up with documentation that sounds good but misses what really matters.

Helping developers build this kind of expertise isn’t optional. AI can help with drafting and formatting, but it can’t replace human judgment or responsibility. That part’s still ours.

Priority 6. Tailoring Documentation to Audience

Documentation only helps if it’s written with the reader in mind. A new engineer, a product manager, a QA specialist, a field applications engineer, a security reviewer, and someone from compliance all need different levels of detail, language, and focus. AI tools don’t understand that. They generate the same kind of explanation every time, based only on the code, without any sense of who’s going to be reading it or what they actually need. The result is documentation that’s written for other engineers by default, even when the audience is someone from product, QA, compliance, or customer support. Non-engineers tend to ignore the docs and rely on querying human engineers directly, which disrupts their work and pulls focus away from development. Instead of making things clearer, the documentation ends up reinforcing silos and increasing interruptions across the team.

Tailoring documentation means thinking ahead about who’s going to read it and what they’re trying to understand. For engineers, that might mean explaining design rationale, tradeoffs, and edge case handling. For product managers, it could be how the code maps to specific user flows or business rules. For security teams, it might be calling out how data is validated or which components handle sensitive information. For field applications engineers, it’s often about understanding how system behavior can be changed through configuration: what settings are adjustable, what those changes affect, and which options are safe to modify in a live deployment. It also means having enough system-level understanding to quickly localize the root of a problem in the field, especially during active customer use. The same is true for QA specialists. Their effectiveness depends on understanding how all the parts of the system work together, so they can rapidly trace unexpected behavior back to its source. In both roles, finding the problem is often 95 percent of the work. Applying the fix is usually the easy part. These kinds of insights don’t live in the code itself. They have to be written in by someone who understands both the system, the surrounding teams, and the audience they’re writing for.

One habit I pushed hard in our engineering culture was removing internal shorthand, obscure acronyms, and team-specific references that wouldn’t make sense to someone outside the immediate group. I wanted the codebase to be a broadly usable knowledge resource, not something locked behind tribal knowledge. That shift made a huge difference. Our QA team didn’t need to bug engineers to get answers because they had access to a large, comprehensive repository of well-authored documentation that was fully accessible through their browsers. They could explore the architecture, drill into any subsystem, module, class, or file, and understand how the system worked—no IDE needed. The same was true for our field applications engineers. They were able to build a deep understanding of our products and solve real customer problems on the spot during live deployments, all because the documentation gave them the context they needed. That level of access and empowerment helped every part of our business move faster.

When documentation is tailored to its audience, onboarding is faster, decisions are easier, and cross-functional work becomes smoother. Less time gets wasted clarifying things that should’ve been obvious. And there’s another benefit too. Once documentation reaches that level of clarity and completeness, AI tools actually become more effective. Instead of generating generic guesses, they start surfacing insights that are grounded, helpful, and accurate. But it only works if the right context is already there. That’s why tailoring documentation isn’t just a writing skill. It’s a force multiplier across your entire organization.

Priority 7. Filling in Missing Documentation

One of the hardest and most overlooked skills in software development is knowing how to spot and fill in missing documentation, especially the kind that explains why the code exists, not just what it does. That includes rationale, intent, architectural reasoning, business logic, and regulatory constraints. When those layers of meaning are missing, even the best-written code becomes a guessing game.

We’ve seen this problem repeatedly when refactoring third-party code. Poor syntax and bad structure definitely slow developers down, but the biggest issue by far is missing intent. The code gives no clue about the thinking behind key decisions. That lack of context makes it harder to understand, harder to trust, and much harder to maintain.

AI tools don’t help much here. At best, they can tell you a docstring’s missing. But they don’t notice conceptual gaps. They don’t know what tradeoff was made, what edge case is being handled, or what customer complaint triggered the change. And when AI doesn’t know, it doesn’t stay quiet. It fills in the blanks with confident, polished hallucinated guesses that miss the mark.

This is one of the most dangerous traits of LLMs: they generate confident, polished language even when their understanding is wrong or incomplete. Unlike a human developer who might leave a TODO or skip over something they’re unsure about, AI always fills empty space with something that sounds authoritative. That creates a false sense of reliability, hides important gaps in reasoning, and misleads both people and AI tools that rely on that documentation later.

What makes this worse is the volume. Developers, when documenting manually, tend to exercise restraint. They might leave things out, but they rarely flood the codebase with confident inaccuracies. AI, on the other hand, can generate misleading documentation so prolifically that it overwhelms a team’s ability to tell what’s real and what’s not. You don’t just get more documentation, you get more wrong documentation… and it’s harder to spot.

That’s a real problem. Wrong documentation is worse than missing documentation because it misleads both people and the AI tools that read it afterward. It creates a false sense of clarity and gives leaders the illusion that everything’s covered, while the deeper issues stay hidden. This is a new category of technical debt introduced by AI. Hallucinated documentation hides missing context instead of revealing it. It looks polished on the surface but quietly erodes maintainability underneath.

Being able to spot and fill those gaps takes human judgment. Engineers need to learn to ask the right questions. What isn’t being explained? What assumptions are undocumented? What context would be lost if the original author left tomorrow?

AI can’t do that. If your team hasn’t built that skill, AI will just make things worse, faster. It’ll generate more documentation, but it won’t be the kind that matters. The fix isn’t more automation. It’s better habits, clearer expectations, and a culture where great documentation is part of the Definition of Done, not something people scramble to add later. That’s how you get maintainable systems that others can understand, trust, and safely evolve.

Priority 8. Generating Boilerplate Descriptions

All three of these AI tools are strong when it comes to generating boilerplate descriptions. This kind of task plays directly to the strengths of LLMs because it involves summarizing code structure, function names, and parameter types. That information is easy for LLMs to process, and the result is clean, grammatically correct descriptions that help keep surface-level documentation consistent across a codebase.

Among these tools, GitHub Copilot and Cursor offer the most seamless experience, thanks to real-time suggestions and tight IDE integration that streamline high-volume docstring and header generation. CodeRabbit, by contrast, is more geared toward post-hoc review and static analysis, which makes it less effective for injecting large volumes of documentation during active development.

But even with the best tools, there are clear boundaries on what AI can do well.

While AI-generated documentation often looks impressive at first glance, its capabilities drop off sharply when it moves beyond surface-level summaries. In our experience, AI tools do a decent job of adding header-style documentation to functions, classes, and files when prompted blindly across a large codebase. But when it comes to documenting the reasoning inside function bodies, where the real implementation decisions live, the results aren’t nearly as helpful. Getting meaningful comments in those areas requires developers to craft specific prompts for each case, which takes extra time and effort. That limitation further reinforces that today’s AI is most helpful for boilerplate and polish, not for documenting deeper insights.

Still, development leaders should absolutely adopt these tools. They are highly effective at handling the repetitive, time-consuming parts of documentation, like generating summaries for files, classes, and functions. The time savings alone provides strong ROI, especially when applied across large and fast-moving codebases. Automating this layer of work helps reduce developer fatigue, improves consistency, and clears the way for more meaningful contributions.

The real benefit is what that time savings makes possible. Developers can focus more of their energy on the parts of documentation that matter most, like preserving architectural clarity, capturing business intent, and explaining design tradeoffs. AI takes care of the grunt work. Developers should use the time it frees up to focus on the parts only well-trained humans with real-world context can do well.

Priority 9. Language Clarity and Grammar

All three of these AI tools are excellent at producing clear, well-structured text. This kind of task plays right into the strengths of LLMs, since they’re trained to generate fluent, grammatically correct language. When it comes to polishing documentation, they consistently perform well, as you’d expect.

This is especially helpful for teams where writing styles vary or English isn’t everyone’s first language. LLMs clean up grammar, standardize tone, and make documentation easier to read. More importantly, they save developers time. Writing clearly and finding the right words takes real effort. LLMs take care of a lot of that heavy lifting so engineers can focus on what they want to say rather than how to say it.

Good grammar won’t fix unclear thinking, but it makes everything easier to read. When developers provide the right context and LLMs handle the polish, the end result is clearer, more usable documentation for everyone.

Final Thoughts

A dangerous myth in software engineering today is believing that AI will solve your documentation problems.

AI doesn’t understand architecture, explain tradeoffs, or capture business intent. When documentation is missing, it guesses. It hallucinates. And it presents those guesses as polished, confident output. That doesn’t reduce tech debt. It amplifies it.

So what’s the real solution? Upskill your developers.

Most engineers haven’t been trained to write documentation that preserves conceptual integrity, explains rationale, or reflects regulatory context. These are not optional skills. They are essential. And they require more than technical ability. Developers also need regular exposure to the product vision, business goals, and constraints that shape the code. Without that context, even skilled engineers can’t document what truly matters.

That is why developer upskilling needs to be a strategic priority. It’s the only way to unlock the real value of AI tools. The better your teams are at documenting the important parts of a system, the more useful AI becomes.

AI tools like Copilot, Cursor, and CodeRabbit are excellent at generating boilerplate descriptions and improving language clarity. These are the tasks that consume the most developer time. I exhort all my developers to use these tools all day, every day in their documentation efforts, but I also expect them to produce the more important documentation that AI can’t be expected to deliver (i.e., Priorities 1 through 7). I expect my engineering leaders to inspect that work (with the help of homegrown tools), because if you don’t inspect it, you can’t expect it.

The real danger is letting AI create the illusion that documentation is complete when the most important contexts are still missing. Don’t fall into that trap!

The teams that succeed will treat AI as a power tool, not a crutch. They will invest in human clarity, enforce documentation standards, and build a culture where knowledge is preserved through writing, not tribal memory.

Train your developers. Expose them to context. Hold them accountable.

Require them to study classic resources like Code Complete (Second Edition) and Clean Code. You can also now leverage our Edensoft Labs’ training library, which contains 149 lessons illustrated with hundreds of practical examples across six programming languages (C++, C#, Java, Python, JavaScript, TypeScript), each focused on clarity, consistency, and long-term maintainability. This library reflects the practices and principles we’ve used to train our own developers over the last 20 years. And when human developers are well-trained in these skills, everyone benefits: the future maintainers, the product team, and even the AI tools you’ll increasingly rely on.

AI is an amplifier for human documentation efforts. Make sure your human-generated documentation is worth amplifying.

Here are the Agentic Coding Standards I built for my team

Andrew Park — Thu, 28 May 2026 21:12:03 +0000

I developed this standard for my team at Edensoft Labs for agentic coding in defense software, where systems stay deployed for decades and weak code becomes operational risk. Agentic coding tools are powerful, but not magic: they don't write maintainable code on their own, and code generation is just the first part of software delivery. Other essential work includes requirements, specification, verification against real system behavior, and refactoring around it, because agents generate code, but humans must own every line shipped. Here’s an outline of the standards:

Agentic Coding Standards

Tier 1: Requirements

Before any specification is written, the engineer must understand what needs to be built and whether an agent is the right tool to build it. These disciplines apply before any agent session begins. Skipping them is where the most expensive mistakes in agentic development are made.

01 Requirements interrogation

Before specifying a task for an agent, you need to know what you actually need to build. That sounds obvious. It isn’t. The most expensive mistakes in agentic coding happen not because the agent misunderstood the specification, but because the engineer didn’t fully understand the requirement before writing it.

Requirements interrogation is the discipline of surfacing what you don’t know before generation starts. It has 2 stages that happen in order. The first is stakeholder interrogation: before any technical specification is written, the engineer interviews the relevant stakeholders, including clients, product owners, domain experts, or other engineers, to surface assumptions, constraints, edge cases, and competing priorities that haven’t been explicitly stated. The second is agent interrogation: once the engineer understands the requirement, they give the agent a description of the task and ask it to interview them about every assumption, constraint, and edge case it needs to understand before proceeding. Both stages produce written artifacts that are archived after implementation so future engineers and agents can understand not just what was built but why.

Ask yourself these questions before starting any significant agent session. If you answer yes to 2 or more, don’t start an agent session yet. Complete requirements interrogation first:

Am I building something I haven’t built before?
Is there domain knowledge involved that I’m not fully confident in?
Do I have assumptions about what the stakeholder wants that I haven’t verified?
Do I have a clear understanding of the quality attribute mix that defines excellence for this product, and do I know how this task affects it?
Are there constraints I haven’t explicitly identified: security, compliance, integration, platform, or things the system must never do?
Am I uncertain about what “done” looks like for this task?
Could a misunderstanding here cost significant rework?
Could a misunderstanding here cause damage to customer mission outcomes?

[RI1] Conduct stakeholder interrogation before writing any specification. Document what was agreed, what was ruled out, and what remains uncertain: The document is the shared understanding between the stakeholders and the engineer. It’s not a summary of what you already knew. It’s a record of what was surfaced, tested, and agreed.

[RI2] After stakeholder interrogation, conduct agent interrogation. Ask the agent to interview you about every assumption, constraint, and edge case before any code is generated: The agent’s questions often surface gaps in the engineer’s own thinking that stakeholder interviews didn’t catch. The output is a refined written specification capturing the shared understanding between the engineer and the agent.

Return to stakeholder interrogation whenever agent interrogation reveals unanswered requirements questions. Engineers’ bias toward building over requirements discovery makes this one of the most common mistakes in software development.

[RI3] Both interrogation outputs are written artifacts stored in a durable location, not in memory or a chat window: Artifacts held only in memory or a chat session are lost. A written document that lives in a durable location gives every future engineer and agent access to the reasoning behind the decision.

Tier 2: Planning

These disciplines govern how the engineer translates requirements into a clear agent session setup. The agent is not yet generating code. The engineer is defining what the agent will do, confirming the task is suitable for agent execution, and establishing the constraints and verification mechanisms that will govern the session.

02 Task division and agent scope

Before directing an agent, the engineer needs to answer 2 questions: is the task fully specified, and can the output be independently verified? Getting both right is what separates agents that produce genuine leverage from agents that produce impressive-looking output that doesn’t hold up. Getting either wrong wastes time, burns token budget, and produces code that has to be discarded.

The first condition is specification clarity: can the task be fully specified, including constraints, edge cases, and what must not happen? The second is independent verifiability: can the output be checked without relying on the agent’s own explanation of what it did? These 2 conditions are the gate for autonomous and multi-agent workflows.

Agents fill underspecified gaps with defaults from their training data, not from your system’s requirements. An agent that doesn’t know the constraint won’t ask. It will make a plausible choice and move on. An agent whose output can only be evaluated by asking the agent whether it worked has not been verified. It has been trusted. Those are not the same thing.

A single agent producing a draft for immediate human review can operate under a lighter standard because the human is the verification mechanism.

[TD1] Before any significant agent session, confirm the task is fully specified and the output is independently verifiable: Both conditions must be satisfied before generation begins. These are the conditions under which agent output is trustworthy enough to enter a production codebase.

[TD2] If either condition is not yet met, complete the preparation work before starting the agent session: Specification gaps require more requirements work, design work, or stakeholder interrogation. Verification gaps require building a test harness, defining acceptance criteria, or identifying the system behavior the output must match. These are engineering tasks, not agent tasks. Starting the agent session before this work is done wastes tokens and produces output that can’t be safely accepted.

[TD3] If either condition can’t be satisfied, keep the agent in exploratory mode. Exploratory output should not be committed to the mainline until both conditions are met: Exploratory agent work surfaces questions, generates options, and exposes constraints the engineer hadn’t considered. That output informs the specification. It doesn’t become production code until both conditions are met.

Tier 3: Foundational engineering habits

These are the habits every engineer on this team builds and maintains regardless of experience level. They govern what happens from the moment the agent begins generating output through the moment that output is accepted into the codebase.

03 Specification before generation

Requirements interrogation surfaces what to build. Task division confirms the work is ready for an agent. This discipline covers the third step: translating that understanding into a precise technical specification the agent can execute from, before any code is generated. The generation is the fast part. The specification is the work. Frame the session as a planning conversation, asking the agent to walk through options, explain what it would need to know, or describe what it understands before building. The built-in plan modes in most AI coding tools are insufficient on their own: they produce shallow plans that miss constraints, edge cases, and architectural implications. Treat them as a first pass, not a complete specification.

Before starting a specification conversation, re-read the relevant documentation, constraints, and architectural decisions in the codebase. The specification you give the agent is only as good as your current understanding of the system, and that understanding needs to be grounded in what is actually documented.

Before telling the agent to build anything, ask it to describe what it understands about the task, what it’s uncertain about, and what information it would need to proceed confidently. A 2-minute planning conversation that surfaces a misunderstanding costs almost nothing. A PR review that catches the same misunderstanding after the agent has generated 500 lines costs significantly more in both review time and token usage.

[SP1] Complete the specification conversation before any agent generates code: The generation is the fast part. Starting without a complete specification produces vague code quickly.

[SP2] Document constraints, invariants, and edge cases before generation starts: The agent needs to know what to build, what it must preserve, what it must not break, and what conditions it hasn’t been told about yet.

[SP3] Be explicit about what must not be sacrificed in pursuit of the objective: An agent given a single goal will optimize for that goal and ignore everything else. The spec isn’t just a description of success. It’s a list of constraints that define the boundaries of acceptable solutions.

04 Empiricism before action

Agents assume. You verify. An agent allowed to diagnose and fix based on assumptions will be wrong in ways that are hard to detect, because the fix will be internally consistent with its assumptions even when those assumptions are false. Show the agent the real data, read what it sees, and confirm its understanding before it touches anything.

[EM1] Before diagnosing or changing code, the agent must inspect actual data, logs, errors, tests, and system state: Don’t let an agent act on an assumption about system state. Require it to show you what it found before it touches anything.

05 Verification before trust

AI output looks polished, and polished is easy to mistake for correct. When agent-generated output contains confident but wrong rationale and that rationale gets documented and merged, it becomes the foundation future agents read and build on. Wrong documentation propagates. The agent that reads it next will treat it as authoritative and extend it.

An agent writing tests for its own code will write tests designed to pass against what it just built, not tests that probe whether the code does what the system actually needs. Independent verification defined before the agent generates anything is the only reliable check. If the agent can read your tests while it works, it will optimize for passing them.

The size of a change is not a reliable indicator of how much verification it needs. A large mechanical refactor is easier for an agent to execute correctly than a small change where the agent needs to understand why, not just what. For the mechanical change, the agent pattern-matches. For the other, it has to reason about constraints it may not fully understand, and that’s where errors happen.

Code that meets our Code Maintainability Best Practices standard gives the agent significantly more to work with. When constraints, invariants, and the reasoning behind decisions are clearly documented in the code, the agent can read them directly instead of guessing. That reduces the risk substantially. Code that doesn’t meet that standard leaves the agent filling those gaps with its defaults, which are shaped by its training data, not your system. The better your documentation, the safer the agent’s work will be on changes where it needs to understand why. This is one of the most concrete reasons our documentation standards exist.

Define your verification criteria before the agent generates the code. Criteria written after reviewing the output are shaped by what the agent produced, not by what the system actually needs.

[VT1] Every piece of agent-generated output is verified against actual system behavior before being accepted, regardless of how confident the agent appeared: Confidence is not correctness. Verify against the system, not against the agent’s explanation of the system.

06 Document the why

Agent-generated code can be functionally correct, pass all tests, and still become dark code the moment it enters the codebase without documented intent. The code shows what was built. Only the engineer knows why it was built that way, what constraints shaped the solution, and what must not be changed without understanding those constraints. If that reasoning stays in the engineer’s head or the chat session, it’s lost the moment the session ends. The next engineer or agent to touch that code starts from zero.

Documenting the why is not a cleanup task. It happens as the agent generates, not after. The engineer directs the agent to document intent, rationale, and constraints inline as it produces code. A codebase where every significant decision is explained at the point of decision gives future engineers and agents the context they need to work safely. A codebase where that reasoning is absent is one that accumulates dark code with every session.

[DW1] Direct the agent to document intent, rationale, and constraints inline as it generates code: Like human developers, agents have a bias toward producing working code over producing maintainable code. Even when directed to document intent inline, an agent will often skip it in favor of completing the coding task. Don’t rely on the instruction alone. Direct the agent to document intent as it generates, then at the end of each run, before closing the session, direct it to review its output and fill any documentation gaps. The reasoning is still fresh in the session context; that window closes the moment the session ends.

[DW2] Every significant decision made during an agent session must be traceable in the code: What was built, why it was built that way, what constraints shaped the solution, and what must not be changed without understanding those constraints. If a future engineer or agent can’t recover this from reading the code alone, the documentation is incomplete.

[DW3] Don’t accept agent-generated code that lacks documented rationale for significant decisions: Treat missing documentation as a defect, not a style preference. An agent that generates without documenting is producing code that’s functionally correct today and unmaintainable tomorrow.

07 Refactor before you merge

Agent-generated code is a starting point, not a deliverable. Agents can produce code that works and passes tests while still lacking architectural fit with the existing codebase. They introduce duplicate logic, organize code in ways that conflict with existing structure, and mix approaches within the same module. These problems are visible to anyone with strong maintainability instincts. This is what technical debt at machine speed looks like: not a single catastrophic decision, but hundreds of functionally correct ones that nobody with the right instincts reviewed.

[RF1] Refactor for architectural fit before review: Code that works but doesn’t fit the architecture creates debt on merge. Fix it before it becomes someone else’s problem.

[RF2] Refactor for naming consistency before review: Agents default to their own naming conventions, not yours. Inconsistent naming makes a codebase unreadable fast.

[RF3] Refactor for duplication before review: Agents frequently reimplement logic that already exists. Duplicate logic means 2 places to change when requirements shift.

[RF4] Refactor for simplicity before review: Agents bias toward complexity. If a simpler solution exists, the agent probably didn’t find it. You have to.

If you get RF1 through RF4 backward and start with whether the feature works, a clean diff and passing tests will trick you into approving design damage every time. RF1 through RF4 are actions the submitting engineer takes before review. The following 5 questions are what the reviewer applies before approving:

[RF5] Does it fit the existing architecture?: If the code introduces a pattern that conflicts with how the rest of the system is organized, it doesn’t belong here yet.

[RF6] Does it preserve conceptual integrity?: The system should feel like it was designed by one mind. Every addition either reinforces that or erodes it.

[RF7] Does it introduce complexity that wasn’t worth the cost?: New complexity should solve a real problem. If the simpler version would have worked, use it.

[RF8] Does it damage quality attributes that matter more than the feature itself?: Know your product’s quality attribute priorities before you approve. A feature that ships faster at the cost of maintainability or security is a bad trade.

[RF9] Is this the simplest good solution, or just the fastest plausible one?: Fast and plausible is how dark code enters the codebase. Simple and correct is what we’re building toward.

Tier 4: Agent supervision skills

These disciplines start at the individual engineer level and become critical as team size grows. A single engineer directing agents needs task boundaries, active monitoring, and accountability discipline just as much as a team of engineers does. When multiple engineers are running agent sessions simultaneously, the coordination demands multiply: individual output velocity can explode while system coherence degrades. If you’re seeing 2 or more of these symptoms, your agents may be producing code faster than your team can coordinate on what’s going into the system:

Duplicate logic appearing independently across modules
Inconsistent patterns for solving the same problem
Abstractions that conflict with each other across the codebase
Dependencies that nobody on the team intended to introduce
PRs that are locally coherent but don’t fit the system’s overall design

The response is tighter workflow discipline, more frequent architectural alignment across engineers, and explicit checkpoints where the team reconciles what each agent has produced against the system’s overall design. Velocity that destroys coherence is not productivity.

08 Task boundaries and structured workflows

Agents drift as work gets dense: making assumptions they shouldn’t, skipping steps, crossing responsibility boundaries quietly. The only control is breaking work into small, well-defined tasks with enough checkpoints that drift doesn’t go undetected for long.

[TB1] Break agent work into bounded tasks with clear checkpoints: Each task should have a defined start state, a defined end state, and a way to verify the agent reached the right end state before moving on.

Even for seemingly well-defined tasks, before the agent executes anything, ask it to map its intermediate steps and review them before giving the go-ahead. A task that looks like a clean A to B may involve decisions at each intermediate step that the agent would otherwise make silently during execution. Having the agent articulate those steps first surfaces specification gaps and gives it explicit anchors to return to if it starts to drift. The planning step costs almost nothing relative to discovering a specification gap mid-run (see CU3).

[TB2] Build a validation loop into the task wherever possible: An agent that can close its own validation loop catches its own errors faster and requires less corrective supervision. Build the verification mechanism before you build the feature.

[TB3] When agent output gets shaky, reduce the scope. Tighter boundaries produce more dependable agents: If a task is too large, the agent will drift, forget constraints, and produce output that doesn’t match the task definition. Reduce the scope of the task. A well-bounded task is more dependable than a large one, regardless of how long the session has been running.

No single agent pass can simultaneously optimize for functional correctness, architectural fit, naming consistency, maintainability, and your product’s quality attribute priorities. The model won’t reliably hold all of those constraints at once.

[TB4] Specification first. Generation second. Verification third. Refactoring fourth. Each pass has one job: Breaking it into passes gives each constraint a chance to be applied properly. That’s how you get to code that meets all the standards, not just the ones the agent happened to prioritize.

Keep the work plan for any multi-session task in the codebase as a simple document tracking what needs to be done, what’s done, and what comes next. Agents have no persistent memory between sessions. Each session starts completely fresh, with no knowledge of prior decisions, completed work, or the reasoning behind either. A durable work plan in the codebase is the only reliable way to maintain continuity across sessions.

Treat agent skills, system prompts, and orchestration configurations as production code. Version control them, document their purpose and constraints, and test them before relying on them in real work. A prompt stored only in a chat window or someone’s memory has no history, no review, and no way to recover when it stops working.

[TB5] For significant multi-step work, structure the workflow as an orchestrator session directing subagent sessions: The main session acts as a lightweight orchestrator: it manages task state, coordinates handoffs, and incorporates human feedback. Each significant subtask is delegated to a separate subagent session with its own clean context window focused on a single task. This pattern prevents context pollution proactively. Each subagent starts fresh with only the context it needs, produces more reliable output, and costs fewer tokens per task than a single long session attempting everything in sequence. Use a task list in the codebase to track what each subagent has completed and what comes next. When handing off between sessions, frame the handoff as a prompt for the next agent rather than a narrative summary. The next session can use it directly as its opening context. Sanity check the handoff before closing the session to confirm it is coherent and complete.

[TB6] When working in a single session, manage context rot by ending the session early and handing off deliberately: Agent reliability degrades as sessions grow longer and context fills up. As more tokens accumulate, reasoning quality declines and information from earlier in the session gets lost. In our experience, degradation becomes noticeable when the context window reaches 25-40% capacity. When output gets unreliable, ask the agent to write a handoff prompt for the next session covering what was decided, what was completed, what the next step is, and what context the fresh session needs to proceed. The same degradation that caused you to end the session also affects the agent’s ability to accurately summarize what it completed, so review the handoff carefully before closing the session. An incorrect handoff will cause the fresh session to build on wrong assumptions. Once verified, that handoff prompt becomes the opening context for the fresh session, along with the current architecture diagram and the relevant prior code.

09 Active agent monitoring

Structured workflows define the plan. Active monitoring is what keeps execution on track. Agents drift, cross responsibility boundaries quietly, and interpret ambiguous instructions in ways that are locally coherent but globally wrong. Catch drift early, while it’s cheap to correct.

Different agent tools require different supervision approaches. Some agents work interactively in a conversation, where you can redirect at any point throughout the session. Others run autonomously on a defined task and hand back results when done, so supervision happens at the handoff. Know which mode your agent is operating in and adjust how you check its work accordingly.

Agents can drift quietly while all visible indicators stay green. Tests pass, diffs look reasonable, and problems accumulate invisibly until they’re expensive to fix. The only reliable check is inspecting what the agent produces during the session, not just at the end.

Build constraints into the system for any action where a mistake would have serious consequences. An instruction to an agent carries no guarantee because agents are by nature probabilistic. They can drift, be inconsistent, or simply get it wrong, and even your clearest instruction won’t stop that from happening. A system-level constraint will be your guardrail against this risk.

[AM1] Inspect intermediate output during the session, not just the final diff: By the time you see the final diff, the agent may have made a dozen architectural decisions you didn’t intend.

[AM2] For actions that can’t be undone, remove the capability structurally: If the action can’t be undone and an agent performs it incorrectly, no amount of engineering discipline after the fact can recover the situation. Remove the capability at the system level before the session begins.

[AM3] Don’t rely on agent instructions to prevent destructive actions: File system permissions, database roles, and branch protection rules make destructive actions structurally impossible. Instructing an agent not to destroy things reduces the risk. It doesn’t eliminate it. Instructions are probabilistic. Architecture is not.

[AM4] When you review agent-generated code, it’s your responsibility to ensure it’s built on correct assumptions about the system, not just whether it works: Agents increasingly catch and fix syntax errors before returning output, but they frequently produce code built on wrong assumptions. These failures don’t show up in tests because tests only catch what someone thought to test for.

Engineer-defined tests encode judgment the agent doesn’t have: what the system must do, what it must not do, and what edge cases matter in this domain. They’re only as good as the engineer’s understanding of the system, which is why the disciplines in Tier 1 and Tier 5 matter.

Automated tests that the engineer defines before reviewing the output are one of the most effective mechanisms for validating assumptions. The human's domain knowledge determines what to test for, and the tests encode that judgment independently of the agent.

[AM5] Implement hooks to enforce structural constraints deterministically in the agent's execution pipeline: Hooks are deterministic code that executes at defined points in the workflow regardless of agent instructions or behavior. Use them to enforce invariants the agent must not violate: file path restrictions, external call rate limits, audit logging, database access controls, and any other constraint where instruction-based enforcement is insufficient. A hook that prevents the agent from writing to a protected path is categorically more reliable than an instruction telling the agent not to. Claude Code supports a ‘.claude/settings.json’ configuration file at the organization, workspace, and repo level where you can define explicit allow, ask, and deny permissions for specific actions. This is a direct structural implementation of AM5 and AM3. Other major agentic coding tools don’t currently offer an equivalent. This capability is likely to become standard across the industry. As soon as your tool supports it, use it. Ask the agent to help generate the initial permission configuration; it will often identify permission boundaries you hadn’t thought to specify.

[AM6] For large or architecturally significant agent runs, ask the agent at the end of the session to list any decisions it made that weren't explicitly covered in the specification: Apply this when the diff is too large to trace line by line, or the task touched architectural boundaries: shared interfaces, data models, external integrations, invariants, or anything other components depend on. On long runs, agents will commonly fill specification gaps with their own judgment without telling you it has done so. Triage the list: rework decisions that conflict with the architecture, and document those that are acceptable so they become part of the codebase's traceable rationale.

10 Review discipline that scales with output

If our agents produce 5x the code we used to, our review process has to handle that volume without degrading. A review process that rubber-stamps agent-generated PRs because the tests passed isn’t a review process. It’s a vulnerability pipeline.

As your use of agentic tools increases, review capacity has to scale with it. More agent output means more review load. If you don’t plan for that explicitly, reviews get rushed and the quality bar drops. Plan for how much you need to review, not just how fast you can produce.

[RD1] Reviewers must evaluate agent-generated PRs for pattern consistency, architectural fit, and maintainability, not just test results: Test results tell you whether the code works. They don’t tell you whether the code belongs in this system.

[RD2] Apply RF5 through RF9 before approving any agent-generated PR: These are the minimum questions every reviewer asks. If you can’t answer all 5, the PR is not ready to merge.

11 Accountability for agent output

Although generating code now is much cheaper, owning it in production costs exactly what it always did. Every engineer who has led a team knows this feeling: although you didn’t write that code, your name is on it because you let it ship. That’s exactly the accountability standard that applies here. Every line an agent produces carries the same long-term maintenance burden as a line you wrote by hand. The volume goes up. The ownership cost doesn’t go down.

Accountability doesn’t move to the tool. When nobody is really responsible, technical debt grows because nobody feels empowered to push back. I expect this team to push back.

Agent workflows are production code. Document them to the same standard we hold all production code to in our Code Maintainability Best Practices training. A workflow that only works because one engineer understands how it was built is a liability. Any engineer, current or future, should be able to read the documentation and take full ownership of it.

[AC1] If you check in agent-generated code, your name is on it. Review it accordingly: The agent generated it. You’re responsible for it. That accountability doesn’t transfer to the tool, the model, or the person who asked you to ship faster.

[AC2] Ownership means comprehension. If you merged it, you can explain what it does, why it was built that way, and what it touches in the system: Code you can’t explain is dark code, and dark code is a liability you’ve signed your name to.

Ownership also includes documentation. If the rationale for significant decisions is not in the code, the next engineer or agent starts without the context that shaped your solution. See discipline 06 Document the why.

12 Cost-effective agent usage

Agentic coding gives one engineer the output leverage of several manual coders at a fraction of the labor cost. The goal is not to minimize token usage. The goal is to maximize engineering leverage. A cheap session that produces shallow reasoning, weak verification, or fragile code is not cost-effective. A more expensive session that saves hours of engineering time, reduces review burden, or prevents rework is a good trade.

The most expensive agent sessions usually start with weak specification. A vague prompt that produces the wrong code and requires 3 correction cycles costs several times more than a well-specified session that gets to the right design before generation begins. Those correction cycles also produce larger diffs, confused architecture, and more review burden. Cost discipline starts with SP1 through SP3.

Agents are not a substitute for simpler deterministic tools. Search, grep, test runners, linters, type checkers, compiler errors, and log analysis often answer narrow questions faster, cheaper, and more reliably than asking an agent to reason its way to the same answer. Use the agent where reasoning, synthesis, planning, or refactoring judgment is actually needed.

[CU1] Optimize for engineering leverage, not raw token minimization: The cost of agentic coding should be evaluated against engineer time, review time, defects, rework, and technical debt. Saving tokens while wasting human judgment is a bad trade.

[CU2] Before any significant agent session, define the question being answered, the files in scope, the expected output, and when to stop.

[CU3] Before the agent executes a task, ask it to map its intermediate steps and review them before giving the go-ahead: A planning prompt costs a negligible number of tokens. A task that looks like a clean A to B may involve several intermediate decisions the agent would otherwise make silently during execution. Reviewing the plan before execution surfaces specification gaps early and gives the agent explicit anchors that reduce drift during the run.

Open-ended exploration through the codebase is one of the fastest ways to burn cost without producing value.

[CU4] Match the model to the task. Use lighter models for mechanical work and reserve frontier models for tasks that require complex reasoning: Using a frontier model for mechanical work, such as formatting, renaming, boilerplate generation, or simple refactors, wastes token budget without improving output quality. Reserve more capable and expensive models for tasks that require architectural reasoning, complex domain judgment, or synthesis across large amounts of context. Most agentic coding tools support model selection at the session or task level. Use it deliberately.

For high-stakes or expensive sessions, run a small evaluation pass across model options before committing to the full session. A few test prompts against candidate models costs a fraction of a failed long session.

[CU5] Provide the context that matters for the task, organized so the agent can reason from the right facts: Unfocused context dumps waste tokens and can dilute the agent’s attention. Give the agent architectural context, constraints, invariants, prior decisions, and relevant examples for this specific task.

[CU6] Don’t make the agent rediscover context you already have: If you know the relevant files, design decisions, error logs, or prior attempts, provide them up front. Making the agent search for information you already have wastes tokens and increases the chance it builds on the wrong assumptions.

[CU7] Stop and rescope when the agent starts thrashing: Repeated failed attempts, circular explanations, expanding diffs, and increasingly complex fixes are signs that the task boundary is wrong or the context is insufficient. Stop, clarify the problem, reduce scope, and restart with better boundaries. If rescoping doesn’t resolve the thrashing, the cause may be context rot rather than task boundary. Apply TB6.

[CU8] Capture useful understanding from agent sessions in durable artifacts: Architecture notes, task plans, decision records, and verified examples in the codebase prevent repeated token burn across sessions. If the agent produced useful understanding, write it down so the next session doesn’t rediscover it.

[CU9] Treat excessive token usage as a workflow problem, not a budgeting problem: It means the engineer didn’t bound the task, supply the right context, use the right tools, or stop when the agent drifted. The fix is better workflow discipline.

Tier 5: Systems engineering discipline

These disciplines require the systems engineering mindset: the ability to hold a system’s conceptual integrity at scale, across time, and across thousands of micro-decisions made by agents that have no understanding of the system’s organizing principles. They develop through years of continuous learning and deliberate practice.

13 Architectural ownership

Agents read files. They don’t see systems. An agent can understand what a function does, what a module contains, and what a class is responsible for. What it can’t reliably reconstruct from reading alone is the structural map of the system: which components call which, how data flows across layers, what the actual impact boundary of a change is. That understanding doesn’t live in any single file. It emerges from the relationships between files, and current agents can only approximate it by reading, which becomes less reliable the larger and more interconnected the system gets. This may improve as the technology evolves, but today the structural gap is real and the human has to fill it.

The engineers who get the most from agentic coding at scale are also the ones doing the most continuous architectural work:

Re-orienting agents at session boundaries.
Pushing back on output that conflicts with established patterns.
Watching for agent decisions that could change the system's structure, and making sure those decisions aren't made by default.

One of the most effective techniques for maintaining architectural continuity across sessions is pointing agents explicitly at prior solved problems in the codebase before generating new code. Every piece of code you write with care today gives future agents a clear example to follow when they work on related problems.

Encode your architectural rules, naming conventions, and structural constraints clearly enough that an agent can check compliance on every PR. Leverage agents to apply well-defined rules consistently and at scale. Don’t trust your agents to make important judgment calls that require understanding the system’s history, trade-offs, and consequences. Those are yours to make.

[AO1] Before every session, re-orient the agent to the architectural patterns and invariants of the system. Don’t assume it remembers: Context resets between sessions. The agent that helped you yesterday has no memory of what you built or why. Reconstruct that context deliberately, or the agent will make architectural decisions from scratch. The most effective implementation of AO1 is a context file that every session reads automatically. AGENTS.md is the emerging cross-tool standard, supported by Claude Code, GitHub Copilot, Cursor, Windsurf, and others, for encoding architectural patterns, invariants, and coding standards at the repo level. Claude Code additionally reads CLAUDE.md. Maintaining this file is itself an engineering discipline: keep it current, keep it precise, and treat it as the architectural memory that persists across every session.

Planning documents, architectural notes, and specification artifacts that no longer reflect the current state of the system are worse than no context at all: they give the agent false confidence about constraints and decisions that may have changed. Before providing prior artifacts as session context, verify they’re current. Outdated artifacts should be marked as historical or removed.

[AO2] Before directing an agent to make a change, trace the full impact boundary yourself. The agent can’t do this reliably: Before directing the agent to make a change, trace the impact boundary yourself: what else calls this code, what invariants could be affected, what tests cover the affected behavior, and what architectural assumptions this change touches. The agent can’t do this reliably. If you don't do it before the session starts, nobody will.

[AO3] Keep system architecture diagrams current. Update them when the architecture changes, immediately, not deferred: These are not planning documents. They’re descriptive of the current state of the system. An agent given an accurate architecture diagram before a session has a structural map of the system that it can’t reconstruct from reading files alone. An outdated diagram is worse than no diagram: it will shape the agent’s reasoning in the wrong direction. Every session where an agent touches architectural concerns should begin with the current diagram in context. Store architecture diagrams as Mermaid files in the repository. Mermaid diagrams are text-based, version-controlled, and readable by both engineers and agents. This makes the architecture a first-class artifact of the codebase rather than a document that lives elsewhere and drifts. When a session touches architectural concerns, ask the agent to propose Mermaid diagram updates at the end of the session. Review and approve them before closing the session. The approved diagram becomes the opening context for the next session.

[AO4] Run an agent-assisted architectural drift scan at minimum monthly, and more frequently on active codebases: Agentic coding sessions each make local decisions that appear reasonable in isolation. Across many sessions those decisions compound. Duplicated implementations of the same concept appear because agents don’t see what was already solved elsewhere. Abstractions become inconsistent because each session invents its own. Dependencies accumulate because agents default to adding rather than reusing. Structural changes happen as side effects of feature work and go undetected until they have calcified. No individual PR review catches this. It only becomes visible when you look at the codebase as a whole.

Configure an AI coding agent to scan for: duplicated implementations of the same concept, abstractions that no longer match the system’s actual structure, dependency growth that wasn’t deliberately chosen, and structural changes that bypassed the architectural review process. The output is a report reviewed by the engineer responsible for architectural ownership. The scan surfaces candidates. The engineer judges what they mean and what action to take. Treating scan findings as authoritative without that judgment is as dangerous as not scanning at all.

14 Simplicity as a forcing function

Agents bias toward complexity because the complicated solutions abound in their training data. They frequently default to Gang of Four design patterns and distributed system architectures where simpler solutions would be superior for maintainability and performance. These defaults are consistent enough that every engineer on the team should be checking for them on every PR, not just the ones with enough experience to recognize them instinctively.

When directing an agent to decompose a problem, orient it toward deeper modules with clean interfaces. Don’t let the agent default to service decomposition unless the operational and organizational case for it is explicit. Agents reach for microservices because they’re well-represented in training data, not because the architecture calls for it.

[SI1] Challenge every new abstraction, layer, dependency, and generalized solution before accepting it: The burden of proof is on complexity, not simplicity. If you can’t articulate why the abstraction is necessary now, it isn’t.

[SI2] Design modules with a small, simple interface and substantial internal functionality: A module built this way is easier for agents to work with for 3 concrete reasons. First, the agent can understand what the module does by reading its interface without having to trace through all its internal dependencies. Second, tests can wrap the module at its boundary and verify behavior without needing to mock a dozen internal collaborators. Third, when the agent makes a change inside the module, the impact is contained and can’t accidentally break something outside the module boundary. Shallow modules force agents to trace dependency chains across many small files to understand what’s happening, and agents that can’t see the full dependency graph make wrong assumptions. This is the same structural blindness problem described in discipline 10, compounded at the design level. The goal is a module with a focused responsibility and a clean boundary, not a god module that absorbs unrelated concerns because they happened to be convenient to add. If a module is growing in ways that make it harder to understand or test, it has crossed the line.

[SI3] Design for Service → Namespace → Class → Method navigability. Any engineer or agent should find the relevant code in seconds and safely ignore 99% of the rest: This is the practical test for whether your simplicity discipline is actually working. If a maintenance engineer has to trace through multiple layers of indirection, hunt across files with no clear organizational logic, or read large amounts of unrelated code to understand what needs to change, the system has failed this test. The same navigability that serves human maintainers serves agents: an agent that can locate the relevant code quickly and ignore everything else makes better decisions, burns fewer tokens, and is far less likely to produce changes that affect code it was never supposed to touch.

15 Domain and product knowledge

Agents make architectural tradeoffs by default, and those defaults reflect the average of their training data, not your product’s actual needs. A naval sensor system needs availability, accuracy, and adaptability. A defense analytics platform needs scalability, performance, and compliance. An architecture that serves one can actively damage another. An engineer who doesn’t understand the product deeply can’t recognize when an agent is optimizing for the wrong quality attributes.

[DK1] Before directing an agent on a feature, understand the user needs, product constraints, and quality attributes that shape the solution: The agent fills the gap with training data defaults, producing code shaped by the wrong product entirely. The debt you create is yours to pay down.

Code that works, passes tests, looks clean, and that nobody can explain is risky "dark code”. Strong discipline is needed to leverage agents to achieve 2x-10x productivity gains. Weak discipline will result in accumulating technical debt at machine speed.

You can get the full 29 page document from my LinkedIn page: https://www.linkedin.com/pulse/engineering-standards-agentic-software-development-edensoft-park-ki1se/

Scaling Human Talent with Gen AI

Andrew Park — Tue, 04 Mar 2025 16:35:01 +0000

The true promise of GenAI isn't 𝐣𝐨𝐛 𝐝𝐢𝐬𝐩𝐥𝐚𝐜𝐞𝐦𝐞𝐧𝐭 but 𝐭𝐚𝐥𝐞𝐧𝐭 𝐬𝐜𝐚𝐥𝐢𝐧𝐠. AI transforms what's possible by amplifying human capabilities in two critical dimensions:

✅ 𝐇𝐨𝐫𝐢𝐳𝐨𝐧𝐭𝐚𝐥 𝐀𝐦𝐩𝐥𝐢𝐟𝐢𝐜𝐚𝐭𝐢𝐨𝐧: When most people think of AI, they imagine multiplying their output—creating digital copies of themselves. You can indeed get more done by adopting AI tools that optimize your day-to-day tasks.
✅ 𝐕𝐞𝐫𝐭𝐢𝐜𝐚𝐥 𝐀𝐦𝐩𝐥𝐢𝐟𝐢𝐜𝐚𝐭𝐢𝐨𝐧: AI bridges the "novice-to-expert gap," allowing less experienced professionals to produce work significantly above their expected skill level.

Forward-thinking companies will drive aggressive AI adoption, transforming employees into more productive cross-functional performers and breaking down traditional siloed job descriptions. For example, software developers will transform into "software composers" who focus on architecture and design while AI handles implementation details.

I shared these insights with the Business Agility Institute as a leader who has carried out aggressive adoption of AI in my organization. Get the report here: https://businessagility.institute/learn/from-constraints-to-capabilities/756. Thanks to Evan Leybourn for the invitation to contribute.

Product Oriented Software Engineering: A Game-Changer for Product Managers and Product Leaders

Andrew Park — Thu, 20 Feb 2025 19:48:13 +0000

At ProductWorld 2025, I shared how my teams have consistently achieved business agility since 2004. We transform software engineers into Product Engineers and implement systematic daily team-wide knowledge sharing. When the engineers have deep product knowledge and visibility into cross-team activities, they can easily take on tactical Product Management tasks and provide engineering expertise without delay to the product team. Product Managers can then focus on strategy, vision, and impact. Our Product Oriented Software Engineering (POSE) approach has consistently increased delivery speed and eliminated the need for detailed user stories.

If you missed the session, you can watch it here: https://youtu.be/POyGLRsJ6Qg. Thanks to ProductWorld 2025 for the opportunity to speak.

Product Owners, Aspire to be Product Managers

Andrew Park — Fri, 14 Feb 2025 20:31:43 +0000

𝐏𝐫𝐨𝐝𝐮𝐜𝐭 𝐎𝐰𝐧𝐞𝐫𝐬, 𝐀𝐬𝐩𝐢𝐫𝐞 𝐭𝐨 𝐛𝐞 𝐏𝐫𝐨𝐝𝐮𝐜𝐭 𝐌𝐚𝐧𝐚𝐠𝐞𝐫𝐬.
Today's great Product Managers will be tomorrow's CEOs. I encourage the Product Owners I meet to start amassing Product Management skills and experiences. Each new capability adds value to the business.

Watch the video at https://youtu.be/qwTduD1ms1U.

Generative AI's Unprecedented Opportunity to Scale Human Talent

Andrew Park — Tue, 04 Feb 2025 21:36:27 +0000

GenAI is closing the novice-to-expert gap by amplifying human talent. AI doesn’t just help you get more done – it helps you do things you never thought you could do.

✅ Horizontal Amplification: When most people think of AI, they imagine multiplying their output—creating digital copies of themselves. You can indeed get more done by adopting AI tools that optimize your day-to-day tasks.
✅ Vertical Amplification: AI helps you bridge the gap between novice and expert faster than you ever thought possible. Novices can now produce expert-level work far earlier in their professional journey.
✅ Deepen Your Skills: AI empowers you to tackle challenges beyond your comfort zone.

𝗥𝗲𝗶𝗺𝗮𝗴𝗶𝗻𝗶𝗻𝗴 𝗔𝗴𝗶𝗹𝗲 𝗮𝗻𝗱 𝗦𝗰𝗿𝘂𝗺 𝗳𝗼𝗿 𝗣𝗿𝗼𝗱𝘂𝗰𝘁 𝗠𝗮𝗻𝗮𝗴𝗲𝗺𝗲𝗻𝘁 (𝗜𝗻𝘀𝗶𝗴𝗵𝘁𝘀 𝗳𝗿𝗼𝗺 𝗧𝗶𝗲𝗻 𝗬𝘂𝗮𝗻)

Andrew Park — Sat, 09 Nov 2024 17:00:00 +0000

In a recent conversation with experienced product manager Tien Yuan, we delved into the challenges of using traditional Agile and Scrum frameworks in product management. Tien shared insightful ideas on how to rebalance the workload, improve team alignment, and create more adaptable processes:

💬 “Too often, product managers end up as the ‘glue’ holding everything together. It’s exhausting and unsustainable, and it doesn’t have to be this way.”

💬 “A senior engineer should be more than a coder—they should be a partner in designing the future.”

💬 “It’s not enough to iterate quickly; we need to ensure that our teams are moving in the right direction. Alignment is critical to make sure that rapid iteration doesn’t just produce faster output but more meaningful outcomes.”

Tien emphasizes that reimagining Agile and Scrum requires a shift from process-oriented thinking to a more strategic, outcome-focused approach. Read the full article to explore how better collaboration, flexible frameworks, and strategic alignment can transform product management: https://www.edensoftlabs.com/post/raspmity

🚀 𝗥𝗲𝗶𝗺𝗮𝗴𝗶𝗻𝗶𝗻𝗴 𝗔𝗴𝗶𝗹𝗲 𝗮𝗻𝗱 𝗦𝗰𝗿𝘂𝗺 𝗳𝗼𝗿 𝗣𝗿𝗼𝗱𝘂𝗰𝘁 𝗠𝗮𝗻𝗮𝗴𝗲𝗺𝗲𝗻𝘁 (𝗜𝗻𝘀𝗶𝗴𝗵𝘁𝘀 𝗳𝗿𝗼𝗺 𝗔𝗱𝗮𝗺 𝗘𝗹𝗹𝘀𝘄𝗼𝗿𝘁𝗵) 🌟

Andrew Park — Fri, 08 Nov 2024 17:00:00 +0000

I recently spoke with Adam Ellsworth, Senior Product Manager at Lucid Software, about why Agile and Scrum often fall short in supporting product management efforts—particularly when engineers lack product and domain knowledge. Adam shared key insights from Lucid, where fostering a more product-aware engineering culture has led to better collaboration and outcomes.

Key takeaways for Product Managers, Product Leaders, and CEOs:
• 𝗘𝗻𝗴𝗶𝗻𝗲𝗲𝗿𝘀 𝗻𝗲𝗲𝗱 𝗽𝗿𝗼𝗱𝘂𝗰𝘁 𝗰𝗼𝗻𝘁𝗲𝘅𝘁: Traditional Agile assumes engineers understand the what and why, but they’re often focused only on the how. This leads to misaligned execution and makes product managers overburdened with tactical details.
• 𝗟𝘂𝗰𝗶𝗱’𝘀 𝗮𝗽𝗽𝗿𝗼𝗮𝗰𝗵: At Lucid, culturally encouraging engineers to accumulate product knowledge has resulted in more informed decision-making and less micromanagement, allowing product managers to focus on strategic work and customer engagement.
• 𝗦𝗵𝗶𝗳𝘁𝗶𝗻𝗴 𝗳𝗿𝗼𝗺 𝗲𝘅𝗲𝗰𝘂𝘁𝗶𝗼𝗻 𝘁𝗼 𝘀𝘁𝗿𝗮𝘁𝗲𝗴𝘆: When engineers understand the product’s mission, design choices improve, collaboration strengthens, and product managers can dedicate more time to driving vision and growth.

Read the full article to see how evolving Agile and Scrum can create a more sustainable and strategic product development process!
👉 https://www.edensoftlabs.com/post/raspmiae

🚀 𝗥𝗲𝗶𝗺𝗮𝗴𝗶𝗻𝗶𝗻𝗴 𝗔𝗴𝗶𝗹𝗲 𝗮𝗻𝗱 𝗦𝗰𝗿𝘂𝗺 𝗳𝗼𝗿 𝗣𝗿𝗼𝗱𝘂𝗰𝘁 𝗠𝗮𝗻𝗮𝗴𝗲𝗺𝗲𝗻𝘁 (𝗜𝗻𝘀𝗶𝗴𝗵𝘁𝘀 𝗳𝗿𝗼𝗺 𝗦𝗶𝗺𝗼𝗻𝗲𝘁𝘁𝗮 𝗕𝗮𝘁𝘁𝗲𝗶𝗴𝗲𝗿)

Andrew Park — Thu, 07 Nov 2024 17:00:00 +0000

In a recent conversation with product leadership coach Simonetta Batteiger, we examined how Agile and Scrum often fall short in serving the full scope of modern product management. Here’s a breakdown of the key insights:

𝗔𝗴𝗶𝗹𝗲’𝘀 𝗦𝗽𝗿𝗶𝗻𝘁 𝗙𝗼𝗰𝘂𝘀 𝗙𝗮𝗶𝗹𝘀 𝗣𝗿𝗼𝗱𝘂𝗰𝘁 𝗦𝘁𝗿𝗮𝘁𝗲𝗴𝘆

Agile’s focus on rapid, incremental delivery can undermine strategic alignment. “It’s not just about how to ship fast; it’s about solving the right problems and aligning with business goals,” Simonetta emphasizes.

𝗠𝗼𝘃𝗶𝗻𝗴 𝗕𝗲𝘆𝗼𝗻𝗱 𝘁𝗵𝗲 𝗣𝗿𝗼𝗱𝘂𝗰𝘁 𝗢𝘄𝗻𝗲𝗿: 𝗘𝗺𝗯𝗿𝗮𝗰𝗶𝗻𝗴 𝗧𝗿𝘂𝗲 𝗣𝗿𝗼𝗱𝘂𝗰𝘁 𝗠𝗮𝗻𝗮𝗴𝗲𝗺𝗲𝗻𝘁

Simonetta advocates moving beyond the limited Product Owner role to a model that prioritizes discovery, research, and stakeholder alignment. “If product managers are solely focused on churning out user stories, they miss a significant part of their role,” she asserts.

𝗔𝗹𝗶𝗴𝗻𝗶𝗻𝗴 𝗔𝘂𝘁𝗵𝗼𝗿𝗶𝘁𝘆 𝘄𝗶𝘁𝗵 𝗥𝗲𝘀𝗽𝗼𝗻𝘀𝗶𝗯𝗶𝗹𝗶𝘁𝘆

We agreed that coupling authority with responsibility is essential for effective leadership. “You cannot hold product managers responsible for outcomes if they lack decision-making power,” Simonetta says. This alignment is crucial for avoiding frustration and boosting innovation.

𝗔𝗱𝗱𝗿𝗲𝘀𝘀𝗶𝗻𝗴 𝗕𝘂𝗿𝗻𝗼𝘂𝘁 𝗮𝗻𝗱 𝗠𝗲𝗻𝘁𝗮𝗹 𝗪𝗲𝗹𝗹-𝗯𝗲𝗶𝗻𝗴

Burnout rates among product managers range from 40-60%. Simonetta urges delegation of delivery tasks to free up time for strategic work. I’ve implemented this approach since 2004, which has significantly reduced the workload for product managers in my teams.

𝗧𝗵𝗲 𝗙𝘂𝘁𝘂𝗿𝗲 𝗼𝗳 𝗔𝗴𝗶𝗹𝗲 𝗮𝗻𝗱 𝗣𝗿𝗼𝗱𝘂𝗰𝘁 𝗠𝗮𝗻𝗮𝗴𝗲𝗺𝗲𝗻𝘁

Simonetta calls for a shift to a product-oriented delivery model that not only supports rapid delivery but also empowers product managers to drive both customer and business value. “Agile must evolve to include strategic dimensions,” she notes.

👉 Read the full article here: https://www.edensoftlabs.com/post/raspmisb

🚫 “𝗦𝘁𝗮𝘆 𝗶𝗻 𝗬𝗼𝘂𝗿 𝗟𝗮𝗻𝗲” 𝗧𝗵𝗶𝗻𝗸𝗶𝗻𝗴 𝗖𝗿𝗲𝗮𝘁𝗲𝘀 𝗘𝗻𝗴𝗶𝗻𝗲𝗲𝗿𝗶𝗻𝗴 𝗠𝗲𝗿𝗰𝗲𝗻𝗮𝗿𝗶𝗲𝘀, 𝗡𝗼𝘁 𝗠𝗶𝘀𝘀𝗶𝗼𝗻𝗮𝗿𝗶𝗲𝘀 🚫

Andrew Park — Wed, 06 Nov 2024 21:16:00 +0000

In today’s product development world, the “stay in your lane” mentality is holding teams back. When product, design, and engineering operate in silos, collaboration suffers, innovation stalls, and teams become disconnected from the mission. My latest article explores how the 𝗽𝗿𝗼𝗱𝘂𝗰𝘁 𝘁𝗿𝗶𝗼 𝗺𝗼𝗱𝗲𝗹—a unified approach where product managers, designers, and engineers work in continuous collaboration—creates “missionaries” who are deeply invested in the product’s success.

🔑 𝗞𝗲𝘆 𝘁𝗮𝗸𝗲𝗮𝘄𝗮𝘆𝘀:

Why the product trio approach fosters purpose-driven, cross-functional alignment.
The limitations of dual-track Agile and how it can lead to disengaged, task-focused “mercenaries.”
How real-time collaboration (supported by a Flex Engineer role) maintains focus while boosting agility.
The importance of shared goals, real-time feedback, and celebrating cross-functional wins.

By replacing outdated handoffs with a collaborative “𝘀𝘆𝗻𝗰𝗵𝗿𝗼𝗻𝗶𝘇𝗲𝗱 𝗱𝗮𝗻𝗰𝗲,” teams can build products that truly resonate with users. 🌟

👉 Read the full article here: https://www.edensoftlabs.com/post/syltcemnm

𝗥𝗲𝗶𝗺𝗮𝗴𝗶𝗻𝗶𝗻𝗴 𝗔𝗴𝗶𝗹𝗲 𝗮𝗻𝗱 𝗦𝗰𝗿𝘂𝗺 𝗳𝗼𝗿 𝗣𝗿𝗼𝗱𝘂𝗰𝘁 𝗠𝗮𝗻𝗮𝗴𝗲𝗺𝗲𝗻𝘁 (𝗜𝗻𝘀𝗶𝗴𝗵𝘁𝘀 𝗳𝗿𝗼𝗺 𝗦𝗰𝗼𝘁𝘁 𝗦𝗲𝗵𝗹𝗵𝗼𝗿𝘀𝘁)

Andrew Park — Thu, 31 Oct 2024 22:20:50 +0000

In my recent conversation with product strategy expert Scott Sehlhorst, we tackled how Agile and Scrum need a reboot to meet the demands of modern, complex software projects. While Agile and Scrum were groundbreaking, the explosion in software complexity since their inception has revealed significant gaps in supporting strategic, product-centric development.

Key insights from Scott include:

𝗔 𝗡𝗲𝘄 𝗣𝗿𝗼𝗱𝘂𝗰𝘁-𝗖𝗲𝗻𝘁𝗿𝗶𝗰 𝗔𝗽𝗽𝗿𝗼𝗮𝗰𝗵: Traditional Scrum roles and processes were built for a different era. Today’s teams need frameworks that empower development teams as strategic partners, not just order-takers.
𝗖𝗿𝗼𝘀𝘀-𝗙𝘂𝗻𝗰𝘁𝗶𝗼𝗻𝗮𝗹 𝗖𝗼𝗹𝗹𝗮𝗯𝗼𝗿𝗮𝘁𝗶𝗼𝗻: Scott emphasizes that product, design, and engineering must work together continuously, rather than relying on a handoff model. The “product trio” approach ensures that customer value, technical feasibility, and design are aligned throughout the development process.
𝗗𝗲𝗹𝗶𝘃𝗲𝗿𝗶𝗻𝗴 𝗠𝗲𝗮𝗻𝗶𝗻𝗴𝗳𝘂𝗹 𝗖𝘂𝘀𝘁𝗼𝗺𝗲𝗿 𝗩𝗮𝗹𝘂𝗲: Instead of just meeting sprint timelines, iterations should focus on delivering full features that address real customer needs.
𝗗𝗲𝗹𝗲𝗴𝗮𝘁𝗶𝗻𝗴 𝗔𝗴𝗲𝗻𝗰𝘆: Scott shares why empowering teams to determine the how of product builds can unlock greater creativity and faster problem-solving.

Read the full article to explore how an evolved Agile and Scrum framework can drive true business agility. Read more ➔ https://www.edensoftlabs.com/post/raspmifss

🚀 𝐂𝐨𝐦𝐩𝐚𝐫𝐢𝐧𝐠 𝐏𝐞𝐫𝐩𝐥𝐞𝐱𝐢𝐭𝐲’𝐬 𝐏𝐫𝐨𝐝𝐮𝐜𝐭 𝐂𝐮𝐥𝐭𝐮𝐫𝐞 𝐰𝐢𝐭𝐡 𝐏𝐫𝐨𝐝𝐮𝐜𝐭 𝐎𝐫𝐢𝐞𝐧𝐭𝐞𝐝 𝐒𝐨𝐟𝐭𝐰𝐚𝐫𝐞 𝐄𝐧𝐠𝐢𝐧𝐞𝐞𝐫𝐢𝐧𝐠 (𝐏𝐎𝐒𝐄) 🚀

Andrew Park — Wed, 23 Oct 2024 19:57:29 +0000

Recently, Curtis Michelson of Product Tank asked me how Perplexity’s innovative product culture compares with 𝐏𝐫𝐨𝐝𝐮𝐜𝐭 𝐎𝐫𝐢𝐞𝐧𝐭𝐞𝐝 𝐒𝐨𝐟𝐭𝐰𝐚𝐫𝐞 𝐄𝐧𝐠𝐢𝐧𝐞𝐞𝐫𝐢𝐧𝐠 (𝐏𝐎𝐒𝐄). While Perplexity emphasizes parallelization and

autonomy, POSE takes a different approach by bridging the gap between product management and technical teams, fostering mutual understanding and cultivating strong software craftsmanship from within. By integrating AI into daily workflows and enabling scalable, maintainable codebases, POSE sets the foundation for success in even the most complex projects.

In today’s tech landscape, building large, highly complex products means evolving beyond traditional frameworks like Agile, Scrum, or SAFe. 📈

That’s why I developed POSE—a framework designed to empower product managers and engineering leaders to collaborate more effectively, reduce product manager burnout, and deliver high-quality, user-centric software.

💬 Want to dive deeper? Read the full article here: https://www.edensoftlabs.com/post/cppcpose

📘 My upcoming book also offers actionable strategies that promise greater alignment between product management and engineering, streamlining the product manager role, reducing stress, and lowering the risk of burnout. Learn more here: https://www.edensoftlabs.com/book