Untitled Lesson
Skill Matrix
UNLOCK NODES BY LEARNING NEW TAGS.
Why do the same qualities that make a codebase easy for an AI coding assistant to navigate (consistent naming, explicit conventions, minimal hidden magic) also tend to benefit human developers, particularly new team members?
š» Code Challenge | +75 XP
Write a README "Getting Started" section for a Node.js project including install, dev server, test, and lint commands, and document one previously-unwritten team convention explicitly.
A new team member and an AI coding assistant both struggled to find the correct place to add a new database query, due to an inconsistent file-naming convention across the codebase. Reorder the steps to address this.
Task: Reorder the blocks in logical sequence to solve the problem.
A.D.A. Interface
Adaptive Didactic Assistant
Pascual Vila
Frontend Instructor // Code Syllabus
The Error //
Relying on an unwritten team convention that exists only in experienced team members' heads
// Invisible unless someone already knows it verbally
// (an unwritten norm, never documented anywhere)
// Discoverable by anyone, human or AI
"CONVENTION: always validate with Zod before any DB write ā see src/schemas/"The Solution //
An unwritten convention is invisible to anyone who doesn't already happen to know it ā a new team member and an AI assistant are equally unable to discover and follow it, since neither has access to unspoken tribal knowledge. Writing conventions down explicitly, in a context file or contributing guide, makes them actually discoverable.
The Error //
Using inconsistent file or folder naming conventions across a codebase
// Inconsistent, forces searching every time
src/services/order_service.js
src/OrderRepository.ts
src/tests/testOrder.js
// Consistent, predictable, guessable
src/services/orderService.ts
src/repositories/orderRepository.ts
src/services/orderService.test.tsThe Solution //
Inconsistent naming forces exploratory searching every time someone (human or AI) needs to locate a related file, rather than being able to reliably guess its location and name based on an established, predictable pattern ā a real, ongoing navigability cost.