Working with AI: A Human-Centered Approach to Code Collaboration

My coding pace slowed down; AI’s never does. The trick is keeping it from “helping” too much – with good docs, clear prompts, and lots of patience.

Lately, I’ve been experimenting with agentic coding AI—tools like GitHub Copilot and ChatGPT that can read my code, suggest changes, and edit multiple files at once. At first, it felt a little like having a new junior developer on the team: full of energy, always ready to jump in… and occasionally hilariously wrong. Meanwhile, I move slower, more deliberate—but that turns out to be a good match. Over time, I’ve figured out how to work with AI in a way that feels like genuine pair programming.

This approach builds on my earlier reflections on pair programming with AI, where I shared initial experiments and lessons learned.

One of the biggest game changers for me has been using markdown files to guide the AI – primarily README.md, TODO.md, and .github/copilot-instructions.md. I design these files to be human-readable first, so any developer can understand the project at a glance. The AI reads them too, but their main purpose is clarity for humans. This makes collaboration with AI feel like a natural extension of working with a human teammate.

1. Treat Your Repo Like a Shared Workspace

When I first started, I realized the AI could only work with what it could see. It’s like onboarding a new teammate: if they don’t understand the project, they’ll make mistakes.

To help the AI understand the project better, I started:

Keeping the README.md clear about goals, architecture, and current state.
Adding a TODO.md that lists tasks in structured, human-readable detail.
Annotating functions with docstrings or inline comments.
Adding .github/copilot-instructions.md to guide AI behavior safely.

The key is that humans must be able to read these files first. The AI follows them naturally, but clarity for humans is the priority. When I write with this mindset, both humans and AI can work effectively together.

2. Write Clear Instructions and Break Code into Small Units

Much like mentoring a junior developer (we’ve all been that guy), as I discussed in my previous post on AI pair programming, vague prompts can lead to frustrating results. The AI will guess – sometimes spectacularly wrong – and it can waste just as much time as a junior dev who hasn’t understood the task.

To prevent this, I now follow two complementary practices:

Write human-readable mini-specs in markdown
Example:
```
### Feature: Add dark mode toggle
- File: src/components/ThemeSwitcher.tsx
- Requirements:
  - Save preference to localStorage
  - Default to system preference
```
These instructions are primarily for humans – they’re clear, concise, and understandable at a glance – but the AI also uses them to guide its code generation.
Structure code into small, self-contained units
– Break large functions or modules into manageable pieces
– Avoid letting the AI edit monolithic blocks in one go
– Make each “unit” a natural target for mini-specs and PRs

By combining clear instructions with modular code, the AI can work more effectively, and I can review its output efficiently—just like mentoring a junior developer while keeping full control over the workflow.

3. Review Changes Like PRs

AI edits can be ambitious – one time it refactored multiple projects to fix problems that it introduced.

Review the diffs carefully
Run automated tests
Apply formatters and linters

The copilot instructions file reinforces the AI to break changes into manageable units, and because the instructions are readable to humans, I can quickly understand what the AI attempted, just like reviewing a junior developer’s PR.

4. Use Guardrails

Like mentoring a junior developer, I started giving the AI clear boundaries:

Comments like # AI: do not edit below
Consistent naming conventions
.github/copilot-instructions.md as the ultimate guide on how the AI should behave
Optional .ai/ folder for your own organizational notes, style guides, or design references. Copilot doesn’t read this folder automatically, but it’s a great space for humans – or future AI tools – to refer to.

All of these files are human-readable first. That way, the team knows exactly what rules exist, even if they never see the AI in action. Clear guardrails make AI collaboration predictable (mostly) and safe.

5. Let AI Handle Repetitive Work

I’ve started using AI for the tedious stuff:

Updating APIs or variable names across files
Adding logging or telemetry
Standardizing formatting

It’s like delegating grunt work to a junior developer while I focus on architecture and edge cases. Because the markdown files are human-readable, it’s easy to see what the AI is expected to do at a glance.

6. Humans Are Still in Charge

Even after months of pairing with AI, I’m still the “architect in the room.” AI can draft, refactor, and suggest – but I decide what goes into production.

It’s like pairing with a young, energetic developer while you’ve learned the value of patience: fast, occasionally brilliant – but always under your supervision and guidance. And because the instructions are human-readable, I can always double-check the AI’s “understanding” of the task.

7. Iterate and Teach the AI Your Style

Consistency matters. The more my repo follows clear patterns, the better the AI’s output. Over time, it “learns” my style indirectly: commit conventions, file naming, and consistent structure guide its suggestions.

The copilot instructions file acts like a mentor’s handbook – it tells the AI how I expect things done, but any human reading it can see the same rules and patterns. This dual-purpose documentation is what makes AI pair programming scalable.

8. Document for Humans and Machines

When I write docs now, I ask:

Could a human and the AI both understand this well enough to take the next step?

If yes, I know it’s clear. If not, I rewrite. Writing for both humans and AI keeps everyone on the same page.

9. Start Small, Then Scale

I didn’t jump straight into full AI-assisted development. I started with small PRs and simple refactors, then gradually let it take on more complex tasks. Trust builds over time – both ways. The human-readable markdown files help me scale safely, keeping the AI on track while letting humans understand what’s happening at every step.

Closing Thoughts

Pair programming with AI isn’t about replacing developers. It’s about creating a structure where humans and machines collaborate effectively.

For me:

The repo is the shared workspace
Markdown files (README.md, TODO.md, .github/copilot-instructions.md) are the team chat and handbook—human-readable first
Prompts and mini-specs are the design specs
Optional .ai/ folder stores organizational notes for humans or future AI tools

AI doesn’t just generate code—it becomes part of the workflow. It’s like mentoring a junior developer with boundless energy while I provide experience, context, and patience. Clear, readable guidance keeps everyone – human or AI – working together smoothly and safely.