I found that too, so I updated to putting limited comments at the beginning of core files that:
- Describe what the file contains (e.g. endpoints for x with their route names)
- Links to docs that are also in the repo (e.g. bruno files for those endpoints)
The core agent files links out to architectural and product decisions as well (i have a /docs folder for them)
This works better for me and I can get a good result when asking to make sure docs are updated whenever changes are made
