The Cautious AI Champion: What I Learned Onboarding Agents to Legacy Code

When I first volunteered for my company's newly founded AI Champions team, it was because working with AI was (and still is) the most fun I've had in years, yet I keenly felt it's also the most divisive technological advancement of our time.

My team works on a real legacy codebase: the first commit was in 2004. There's no model trained on our highly custom application, and most tools were set up to give broad access -- to humans, not agents. Meanwhile, the team is made up of skeptics, enthusiasts, and the curious alike. Adopting AI in our team posed a real challenge in both change and risk management. This talk is about what I learned doing exactly that for the past 12 months.

Transcript

1. BRABANTPHP · BREDA · AUGUST 20, 2026 The Cautious AI Champion What I learned onboarding agents to legacy code Daniëlle Suurlant · Senior Backend Developer, AlisQI https://dsuurlant.dev
2. About me - Rotterdam - 15+ years of PHP and software development - mental health advocate - fully remote dev @ AlisQI since 2020
3. AlisQI humble beginnings - Quality management for 1 manufacturer - First commit in 2004 - Built by 2 humans with complete access - Fully custom framework (with some Symfony)
4. AI for accessibility - January 2025: double wrist injury - Using dictation + prompts - Poor LLM output quality
5. The AI Champions Team
6. Pilot Projects - Introduce AI tools to each team - Short, measurable, quick wins - “Let’s try AI Code Review”...
7. AI in the dev team = a big project Team raised valid concerns: security, quality Mixed skepticism & interest No existing unified approach for AI assistants or agents Not a pilot or a quick win
8. The AGENTS.md standard
9. Real progress: better context for the model AGENTS.md README.md docs/ How to work in this codebase Why the codebase is like this Detailed component manuals https://agents.md
10. Your AGENTS.md Application stack Gold standard examples Directory structure Quick ‘how to’ approaches Code style What (not) to refactor Conventions & exceptions (slide edit, 23-08-2026) Code review guidelines According to recent research, directory structure and code style are not effective at producing better output! https://arxiv.org/html/2602.11988v2
11. Tip: PHPStorm Chat Instructions
12. AGENTS.md common mistakes Too vague Unclear priorities Conflicting instructions Written for / by humans Too long (> 800 words) Tip: Co-write your AGENTS.md with AI!
13. We need more standards AGENTS.md works but… No standardized “agent ignore” file No standardized “agent block tool use” file No standardized “agent skill” files
14. So what to do? Choose one approach & provider - PHPStorm Junie - Claude Code - OpenCode - Cursor - Gemini - Copilot Switching is easy Maintaining multiple is not
15. The Four Layers of Securing Agents
16. Layer 1: Environment Isolation - Run agentic tools in a container / VM / sandbox - No access to production or your machine by default - No access to files that aren’t mounted … but smart enough agents will attempt to break out
17. Layer 2: Command Allowlisting & Audit Trail Whitelist what the agent is allowed - Agents will try to work around a blacklist - Use deterministic hooks if possible - Deny all by default .claude/settings.json {“hooks”:[“PreToolUse”:{...}]} -> exit 2 Log all commands / tool calls / actions the agent takes Optionally log prompt and/or context
18. Layer 3: File System Restrictions - Agent has separate user role - Agent can only read/write/delete in specific files/dirs - Use an ignore file to hide sensitive files from your agent - Block agent from editings its own config
19. Layer 4: Network Access - Whitelist allowed APIs and URls - Whitelist allowed packages / versions / commands (npm, composer, pip) - Do not store any production credentials on your machine - Agents may still be able to access other Docker volumes
20. Next steps with your agent
21. Finally, the fun part! Create skills for reusable work Apply continuous learning Do code reviews Parallel debugging Define multi-step workflows
22. Be mindful of… Too much context: Less accurate Hyperfocusing on 1 solution Token waste It exists !== it’s correct Understand the problem Understand the fix
23. Questions? Thank you! Daniëlle Suurlant https://dsuurlant.dev