Documentation in "plain english", architecture diagrams, comments, and documentation are notorious for being unreliable, out-of-sync, and not as precise a specification as the code itself.

The issue with using "the code as the spec" is that humans can't read 100K lines of code in a day, can't hold the entire ball of unstructured mud in their brains all at once, and generally require hierarchical "structure".

Modern AIs just don't have these issues! Their context windows are big enough to encompass an entire codebase, so they can "see everything", all at once.

Each line of new code they write is compared against every relevant line of code in the original, which they treat as a spec.

My main issue in my experience is that that AIs tended to reproduce the legacy behaviour "bug for bug", which was not my intention.

Similarly, the AIs were hamstrung by external constraints: I typically prefer to leave the DB schema unchanged, which meant the torturous workarounds were needed for design errors in some stored procedures, etc.

The older the code, the bigger the issues with baked-in assumptions about transactions, stateful sessions, data types, string formats, etc.

This trips up AIs just as much as humans. You can't trivially maintain backwards compatibility and modernise the codebase! Those are conflicting goals, no matter what.