What a 'DO NOT TOUCH' file really is
Most engineering teams have at least one file or module annotated with a terse warning: it does something important, no tests describe it, and no one wants to change it. Those labels are symptoms, not root causes. Typical underlying problems are missing tests, opaque external dependencies, unique deployment assumptions, entangled responsibilities, and absent documentation or ownership.
Here is a representative example you might find in a repository:
// DO NOT TOUCH: This implements the legacy billing calculation used for prior invoices
When a file becomes untouchable, it increases the risk of regressions and slows delivery because teams avoid necessary changes or introduce fragile hacks around the code. For an organisation that depends on continuous delivery and reliable services, those costs are real: increased lead times, higher incident risk, and growing technical debt.
Why an AI that 'summons' the original developer is attractive — and where it fails
The idea of using AI to recreate the intent of the original author — a sort of automated code historian or persona — is attractive because it promises to reduce uncertainty. If the tool can explain why certain choices were made, identify hidden invariants, and recommend safe refactors, a team can make progress faster.
However, there are several engineering and operational limitations to consider before treating such a tool as authoritative:
- Hallucination risk: Models can generate plausible but incorrect explanations. They may invent reasons that sound reasonable without evidence in the repository.
- Provenance gaps: Reconstructing intent from source alone is inherently uncertain. Commit messages, code review comments, and issue threads are useful, but may be incomplete, ambiguous or misleading.
- Attribution ambiguity: Commit history may not map one-to-one to decision ownership. Rebases, bulk formatting commits, and team edits complicate who actually made a design choice.
- Privacy and legal exposure: Training or querying models on internal repositories can surface personal data, credentials or proprietary algorithms. There are also licence risks if external models were trained on copyrighted code without proper permissions.
- Operational risk: If the tool is used to generate code changes automatically, it may introduce regressions unless changes go through the usual verification and approval pipeline.
AI can be useful as an accelerant for understanding, but relying on it without engineering controls replaces human uncertainty with opaque, and sometimes dangerous, model certainty.
Engineering controls and practical guidance
If your team experiments with an AI assistant that explains or suggests edits for legacy files, apply the same controls you use for any tool that affects production systems. The following are pragmatic steps a technical lead or manager should require.
1. Treat AI output as advisory, not authoritative
- Require human review and sign-off for any code change suggested by the tool.
- Record citations in the tool’s output: which files, which commits, and which tests support a claim. If the model cannot point to evidence, downgrade confidence.
2. Preserve provenance and produce confidence scores
- Log the data sources the model used (file paths, commit ranges, issue IDs) and the model version.
- Show a confidence or uncertainty indicator for explanations. Lower confidence should trigger a requirement for additional human research.
3. Keep training and access controls explicit
- Limit the dataset used to train or fine-tune the model and document licensing and privacy constraints.
- Ensure access to the tool is controlled the same way as access to production code. Audit who queries what and when.
4. Integrate with CI, tests and feature flags
- Any automated change must pass existing unit and integration tests. Strengthen test coverage for legacy behaviour before making changes.
- Deploy changes behind feature flags or canary releases so you can roll back quickly.
5. Use the tool to extract information, not to replace knowledge transfer
- Use AI to summarize commit histories, surface relevant review threads, and extract likely invariants — then capture that information in durable documentation or tests.
- Pair the AI with human-driven knowledge capture: interviews with longtime maintainers, focused mob programming sessions, or dedicated grooming tickets.
Approach to safely modernise a 'DO NOT TOUCH' area
Practical refactoring follows a risk-managed pathway. Start by reducing the unknowns and adding safety nets, then make iterative improvements.
- Inventory and triage: List all DO NOT TOUCH files and rank them by business impact and change pressure.
- Characterise behaviour: Use automated tests, static analysis and observability to capture current behaviour. Create regression tests that codify expected outputs for representative inputs.
- Isolate and wrap: Where possible, wrap legacy code in a stable interface or adapter. Route new code through that interface so you can swap implementations incrementally.
- Refactor in small steps: Make one small change per PR, with clear tests and roll-back capability. Do not attempt a big rewrite without first reducing behavioural uncertainty.
- Assign ownership and document: After a safe change, assign a maintainer and update documentation so future teams don’t re-create the “do not touch” stigma.
Practical next steps
For managers and technical leads in Kenya and the region: start with low-friction, high-value actions you can implement with existing resources.
- Run an inventory meeting: identify DO NOT TOUCH files, their owners (or lack of owners), and business impact.
- Require that any AI-based explanation tool must produce a provenance trace and a confidence indicator; block automated changes unless they pass CI and manual review.
- Allocate time in the next sprint for adding regression tests around the highest-risk legacy file, then schedule a controlled refactor behind feature flags.
- Establish access controls and logging for any model that uses internal code as training data. Treat it like privileged infrastructure.
- Document the change process: how the team will use AI tools, who signs off, and how to roll back changes if the tool is ever wrong.
AI can accelerate understanding of legacy code, but it cannot replace the engineering practices that make changes safe. Use the tool to reduce uncertainty — not to eliminate the safeguards that protect the organisation’s systems.
If this affects a system your organization depends on, our software engineering team can help you assess it.
Further reading
Image: Photo from Unsplash.
