AI-Teaching-Assistant-1 Coding Guidelines
Behavioral guidelines combining project-specific rules with universal LLM coding principles derived from Andrej Karpathy's observations.
PROJECT CONTEXT
AI-Teaching-Assistant-1/ monorepo:
- Admin/ — Vue 3 frontend, Port 5173
- Teacher/ — Vue 3 frontend, Port 5174
- Student/ — Vue 3 frontend, Port 5175
- backend/ — FastAPI backend, Port 8000
- Chatbot/ — ABSOLUTE NO-TOUCH ZONE (no edits, no refactors, no "quick tweaks")
Working scope: @Admin, @Teacher, @Student, @backend only.
WORKFLOW: ANALYZE → WEB SEARCH → PLAN → IMPLEMENT → VERIFY
Think Before Coding (Karpathy): State assumptions explicitly. If uncertain, ask rather than guess. Present multiple interpretations when ambiguity exists. Stop when confused — name what's unclear, then ask.
A) ANALYZE
- Identify target base (@Admin / @Teacher / @Student / @backend).
- READ the base code first. Identify entry points/flow, file/modules, existing patterns.
- Explicitly list what you will REUSE (module/file/pattern names) before moving to PLAN.
- Search inside the base to understand how any technique is used there.
- State any assumptions. If you catch yourself guessing, stop and ask.
B) WEB SEARCH (MANDATORY BEFORE CODING)
- Search the Internet to confirm best practices for current versions.
- Prioritize: Official docs → Specs/standards → Issue trackers/release notes.
- If you cannot search: state why + list assumptions + proceed based on codebase patterns.
- Briefly summarize what you found and what you will apply.
C) PLAN
D) IMPLEMENT
- Follow base flow/patterns strictly.
- Reuse first, extend second.
- No random imports; no new layers if base already has an equivalent.
- Keep code clean, responsibilities clear, maintainability high.
E) VERIFY
- Run project / tests / lint using the repo's standard approach.
- Ensure no regressions and no deviation from base flow/patterns.
CORE RULES: "FOLLOW THE BASE FLOW" (NON-NEGOTIABLE)
BASE REUSE RULE — 100% MANDATORY
Before writing ANY new code:
- SEARCH inside the base for existing solutions.
- If it exists → ONLY CALL/REUSE IT following the base flow (no rewriting, no "similar variants").
- If it doesn't exist → you may add it, but it MUST:
- Be placed in the correct layer/folder.
- Follow base naming + export/import conventions.
- Avoid messy dependencies or breaking architecture.
- Explicitly state assumptions before adding. If uncertain, ask — don't guess.
NO HACKS, NO SKIPPING STEPS
- No "shortcuts" or jumping steps.
- No mixing responsibilities / no putting logic in the wrong layer.
- No random cross-imports.
Surgical Changes (Karpathy): Touch only what you must. Clean up only your own mess.
- Don't "improve" adjacent code, comments, or formatting.
- Don't refactor things that aren't broken.
- Match existing style, even if you'd do it differently.
- Mention unrelated dead code — don't delete it.
- Remove only YOUR orphans (imports/variables/functions your changes made unused).
- Don't remove pre-existing dead code unless asked.
- Test: Every changed line should trace directly to the user's request.
CLEAN CODE & LOGIC QUALITY
- Readable, debuggable, maintainable: clear naming, small functions, minimal side effects.
- One primary responsibility per file (SRP); don't push logic into the wrong layer.
- Always handle edge cases: loading/error/empty states, null/undefined, permissions/auth.
- No duplication: extract & reuse; don't "copy logic and tweak a bit".
- Verify important logic changes against regressions.
Simplicity First (Karpathy): Minimum code that solves the problem. Nothing speculative.
- No features beyond what was asked.
- No abstractions for single-use code.
- No "flexibility" or "configurability" not requested.
- No error handling for impossible scenarios.
- If 200 lines could be 50, rewrite it.
- Ask: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
IMPORTS/DEPENDENCIES — DO NOT PULL RANDOM STUFF
- Do NOT add external libraries arbitrarily.
- Only add a new dependency if: base truly lacks the capability AND you proved no equivalent exists inside.
- If you must add: state why + impact + rollback plan.
FILE SIZE & MODULARIZATION
- Hard rule: no file may exceed 1000 lines.
- 500 lines is a warning threshold → split into modules/includes.
- Split by responsibility following the base structure.
BASE-SPECIFIC RULES
@backend (FastAPI)
- Read the base thoroughly: structure, patterns, syntax, existing techniques.
- Follow base naming conventions; do NOT name things randomly.
- Refactor in small steps (no big-bang); don't break layering.
- Maximize reuse of existing router/service/schema/dependency/utils/config.
@Admin / @Teacher / @Student (Vue 3 Frontends)
- The 3 frontends share the same foundation — keep consistent, don't diverge.
- Read how the base organizes pages/components/stores/services/utils and API calls.
- Strictly minimize
<style> inside .vue: only when truly necessary for component-specific styles.
- Prefer existing base classes/mixins/utilities.
- Maximize reuse of state/store patterns, shared components, composables, services.
BUG-FIX WORKFLOW
Goal-Driven Execution (Karpathy): Transform every task into verifiable goals with a verification loop.
- Write a test that reproduces the bug (current behavior must fail).
- Identify root cause via logging/tests — don't assume.
- Fix the code.
- Run tests to verify the fix.
- If tests still fail or logs don't prove the fix: keep iterating until stable.
- Run tests and lint one final time.
For each step, state what "verified" means before moving on.
ALWAYS-ON REMINDERS
- Only work on 4 bases: @Admin, @Teacher, @Student, @backend. @Chatbot is forbidden.
- If you break flow/pattern/architecture or hack shortcuts → redo from scratch.
- If the command contains "yêu cầu trả lời tiếng việt" → respond 100% in Vietnamese.
- After finishing a task, final line MUST be: "Tôi đã sẵn sàng nhận lệnh tiếp theo trong COMMAND SLOT! 🚀"
These guidelines are working if: fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.