Contractors: Specialized, Time-Limited, Must Leave Maintainable Code
Contractors and agencies differ from full-time teams: they are engaged for a specific project or feature, they have a defined end date, and they leave. The code they write must be maintainable by the in-house team after the contractor departs. The biggest contractor risk: delivering working code that nobody else can maintain (proprietary patterns, undocumented decisions, unique dependencies). AI rules mitigate this by ensuring contractors write code in the organization's conventions, not their own.
AI rules serve three critical functions for contractor engagements: rapid onboarding (the contractor is productive in days, not weeks), convention enforcement (the AI generates code in the organization's style, regardless of the contractor's personal preferences), and knowledge transfer (the code follows known patterns that the in-house team already understands).
The contractor AI rules: everything in the standard rules plus: explicit handoff requirements (documentation, test coverage, code walkthrough), prohibition on introducing new libraries without approval, and a focus on simplicity (the in-house team maintains this code forever — complex clever solutions are worse than simple obvious ones).
Rapid Onboarding and Convention Enforcement
First-day productivity: AI rule: 'Contractor onboarding kit: (1) AI rules file (conventions and patterns), (2) getting started guide (local setup in < 30 minutes), (3) assigned feature brief (what to build and why), (4) example PR (a similar completed feature to reference). The AI rules file is the most important document — it tells the contractor's AI tools exactly how to generate code for this project. First PR: expected within 48 hours.'
Convention over preference: AI rule: 'Contractors must follow the project's conventions, even if they prefer different patterns. The AI rules file is authoritative. If the contractor's usual approach differs from the rules: the rules win. This is not negotiable — the code will be maintained by the in-house team who knows these patterns. Exceptions: only if the contractor identifies a genuine improvement, proposed through a PR to the AI rules file with justification.'
Library constraints: AI rule: 'No new dependencies without in-house approval. Contractors sometimes bring their favorite libraries (a different ORM, a different testing framework, a different utility library). Each new dependency is a maintenance burden after the contractor leaves. The AI should generate solutions using existing project dependencies. New dependencies: proposed with justification (why the existing tools cannot do this), approved by in-house tech lead.'
The contractor adds their favorite utility library (15 functions used). The engagement ends. A year later: the library has a critical vulnerability. The in-house team must either upgrade (potentially breaking changes they did not introduce) or migrate off the library (rewriting the contractor's code). Each dependency the contractor introduces is a future maintenance task. The AI should always generate solutions using existing project dependencies first.
Quality Standards and Handoff Requirements
Test coverage requirements: AI rule: 'Contractor deliverables: minimum 80% test coverage on new code. Tests must be: readable by the in-house team (clear names, standard patterns), maintainable (no complex test infrastructure that only the contractor understands), and comprehensive (happy path + error cases + edge cases). The AI generates tests alongside feature code, not as a separate deliverable.'
Documentation requirements: AI rule: 'Every contractor PR includes: updated README (if the feature affects setup or usage), inline comments on non-obvious logic (the in-house team will maintain this — explain the why), and API documentation for new endpoints (OpenAPI or equivalent). Architecture Decision Records for significant decisions: why this approach was chosen over alternatives. The documentation is part of the deliverable, not an afterthought.'
Handoff checklist: AI rule: 'Before the engagement ends, the contractor delivers: (1) all code merged to main with passing CI, (2) test coverage report meeting the minimum threshold, (3) documentation updated, (4) knowledge transfer session (recorded) covering: architecture decisions, known limitations, and future considerations, (5) no open TODOs or temporary workarounds without documented plans. The handoff is not complete until the in-house team confirms they can independently modify and deploy the code.'
A live knowledge transfer session is valuable — but only for the people who attend. Three months later: the developer who attended the session has moved teams. The recording: available forever. Record every contractor handoff session. Store in a known location (docs/handoff/ or the team's wiki). Include: architecture walkthrough, known limitations, gotchas, and future considerations. The recording is the insurance policy against knowledge loss.
Writing Maintainable Contractor Code
Simplicity over cleverness: AI rule: 'Contractor code must be maintainable by mid-level in-house developers. Avoid: complex generic abstractions (that only the contractor understands), unusual patterns (even if technically superior), and deep dependency chains (hard to debug without the original author). Prefer: straightforward implementations, standard patterns from the AI rules, and explicit code over implicit magic. The next person reading this code should understand it in 5 minutes.'
No unique infrastructure: AI rule: 'Contractor code runs on the existing infrastructure. No new databases, no new queue systems, no new caching layers, no new deployment pipelines without in-house approval. Each piece of infrastructure is a maintenance burden. The AI generates code that works with the project's existing technology stack.'
Clean boundaries: AI rule: 'Contractor features should be well-bounded: clear interfaces with the rest of the system, minimal coupling to other features, and easy to modify or remove independently. If the feature needs to be redesigned after the engagement: the in-house team can modify the contractor's module without understanding the entire codebase. The AI generates modular code with explicit interfaces.'
A contractor writes an elegant, abstracted solution using advanced TypeScript generics that handles every edge case through type inference. It works perfectly. But: only the contractor understands it. The in-house team cannot modify it without the contractor's guidance. A simpler implementation with explicit types and straightforward logic: slightly more verbose but understandable by everyone. For contractor code: optimize for readability and maintainability, not elegance.
Contractor Team AI Rules Summary
Summary of AI rules for working with contractor and agency development teams.
- AI rules = rapid onboarding. First PR within 48 hours. Convention file is the #1 onboarding doc
- Convention over preference: project rules win over contractor habits. No exceptions without approval
- No new dependencies: use existing stack. New libraries need in-house tech lead approval
- Test coverage: 80% minimum on new code. Readable, maintainable tests. Not a separate deliverable
- Documentation: updated README, inline comments for non-obvious logic, API docs, ADRs
- Handoff: code merged, tests passing, docs updated, knowledge transfer recorded, no open TODOs
- Simplicity: mid-level developers must understand it. Standard patterns. Explicit over clever
- Clean boundaries: modular features, clear interfaces, easy to modify or remove independently