Guidance for AI agents working in 15-410 Project 3.
Don't assume. Don't hide confusion. Surface tradeoffs.
Before implementing:
State your assumptions explicitly. If uncertain, ask.
If multiple interpretations exist, present them - don't pick silently.
If a simpler approach exists, say so. Push back when warranted.
If something is unclear, stop. Name what's confusing. Ask.
Minimum code that solves the problem. Nothing speculative.
No features beyond what was asked.
No abstractions for single-use code.
No "flexibility" or "configurability" that wasn't requested.
No error handling for impossible scenarios.
If you write 200 lines and it could be 50, rewrite it.
Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
Follow SETUP.md for Simics setup. You can use all simics commands to gather information about the kernel state. For debugging. Recommended commands: https://www.cs.cmu.edu/~410/doc/simics_commands.html You're welcome to use other commands as well.
If you debugged for very long time, look back at your staged/unstaged changes and commit history up til and EXCLUDING fe3216450b1cc992927f2bbf566c3b44286dce15 to see whether those changes introduced any bugs. Do not modify existing untracked files unless you created it. When fixing a bug, you should think whether other places in the codebase could have the similar bug and check those.
For any changes, before you touch any code. Please use the Plan Mode first to write plan. Then implement.
If user want you to debug multiple files, you should NEVER STOP until all tests pass without code changes in between tests.
NEVER STOP: Once started a job, do NOT pause to ask the human if you should continue. Do NOT ask "should I keep going?" or "is this a good stopping point?". The human might be asleep, or gone from a computer and expects you to continue working indefinitely until you are manually stopped or until user request satisfied. You are autonomous. If you're STUCKED, see STUCKED. The loop runs until the human interrupts you, period. You should only do Commits when user requested NEVER STOP.
STUCKED: When you feel stuck, you need to think whether the overall design has bug instead of just trying to adhoc fixes, especially this involves breaking invariants. During your debugging, you can modify the codebase to add more logging or assertions (for invariants), but you should remove logging (but keep invariants checks) before submission. When stucked, ensure code style is good by checking the handling of failure cases, race condition, locking order, ownership, and possible stack overflow.
Unix-like x86 kernel in C + x86 assembly, runs on Simics. Boots, initializes paging, loads init, context-switches between user tasks via round-robin scheduler.
Authors: Hanke Chen (hankec / Koke_Cacao) and Shermern Ang (shermera).
Do not modify 410kern/, 410user/, or spec/. Student code lives only in kern/ and user/.
All config in config.mk. Never edit Makefile.
make # build kernel (bootfd.img + kernel ELF)
Key config.mk knobs:
CONFIG_DEBUG = user kernel adds -DDEBUG to CFLAGS
410TESTS / STUDENTTESTS — programs baked into RAM disk for testing
KERNEL_OBJS — add new .o files here to include in kernel build
No em dash in comments — use hyphen. Minimize - and :. No ; or non-ASCII in comments.
No mention of AI co-authorship in commits or code.
Brace all control flow bodies, even single-line.
Caveman style in comments: short, high-density, grammar expendable.
2-space indentation (TABSTOP = 2 in config.mk). 80-column limit.
snake_case for functions and variables; UPPER_CASE for macros.
After code changes, run clang-format with repo's .clang-format.
Doxygen in .c files only (not .h). For .S files: doxygen in matching .h, inline comments in .S.
Skip obvious inline comments. High info density; grammar sacrificeable.
Error handling: goto cleanup pattern at function end for resource teardown.
affirm(): true invariants only (never-happen cases). assert(): expensive invariant checks (disabled when NDEBUG). Neither for expected failures like OOM.
lprintf() → Simics log. printf() → console. Remove sim_breakpoint() before submission.
Write regression tests in user/progs/<name>.c. Register in STUDENTTESTS in config.mk (never in STUDENTREQPROGS). Keep tests focused: one syscall, scheduler path, or sync invariant per test.
Document your test resuls in tests/testing.log
Short imperative subjects. Emoji prefixes: :robot:. Example: :robot: fix deschedule lock ordering. Do not PR or push, do not use remote.
Table of Content