Skip to slide
029 / 170

CH 03 · Building the Prompt · 06/12

Read as one page

Real code: AGENTS.md is collected from the root down

Your PromptBuilder keeps project_instructions as one string. Codex searches the disk for it. From the working directory it walks up to the project root (the nearest directory with a configured marker, .git by default), then flips the list so the root comes first.

    let search_dirs = if let Some(root) = project_root {
        let mut dirs = Vec::new();
        let mut cursor = dir.clone();
        loop {
            dirs.push(cursor.clone());
            if cursor == root {
                break;
            }
            let Some(parent) = cursor.parent() else {
                break;
            };
            cursor = parent;
        }
        dirs.reverse(); // [1]
        dirs
    } else {
        vec![dir] // [2]
    };

Source: openai/codex, codex-rs/core/src/agents_md.rs (Apache-2.0)

Those files are then read in that order, root first, and cut off when a byte budget runs out.

    for p in paths {
        if remaining == 0 { // [3]
            break;
        }
        // ...
        let mut data = match fs.read_file(&p, ReadFileOptions::default(), sandbox).await {
            Ok(data) => data,
            Err(err) if err.kind() == io::ErrorKind::NotFound => continue,
            Err(err) => return Err(err),
        };
        let size = data.len() as u64;
        if size > remaining {
            data.truncate(remaining as usize); // [4]
        }
        // ... (a warning when the file was cut)
        let text = String::from_utf8_lossy(&data).to_string();

Source: openai/codex, codex-rs/core/src/agents_md.rs (Apache-2.0)

What to notice

  1. [1] The loop collects directories from the working directory up to the root. reverse puts the root first and your current directory last. Codex concatenates every file it found. It does not delete the parent. The closer file comes later, so it can restate a parent rule, but the parent text is still in the prompt.
  2. [2] With no project root, only the current directory is searched. The walk does not continue to the top of the filesystem.
  3. [3] remaining starts at project_doc_max_bytes, which defaults to 32 KiB (DEFAULT_PROJECT_DOC_MAX_BYTES in config_toml.rs). At zero the loop stops. Because the root was read first, the files that get skipped are the ones closest to you.
  4. [4] A file bigger than the bytes left is cut in place with truncate. Your builder would paste the whole file.

Two more cases your builder has no room for. In one directory, candidate_filenames tries AGENTS.override.md before AGENTS.md, and the first file that exists is the one that counts. If the project is untrusted, load_project_instructions returns before the walk, so project files are never read. The joined text is then sent as a user message, wrapped with # AGENTS.md instructions and <INSTRUCTIONS>, not mixed into the developer base prompt the way build_instructions mixes your project string in.

pi's loadContextFileFromDir tries AGENTS.override.md, AGENTS.md, AGENTS.MD, CLAUDE.md, and CLAUDE.MD. loadProjectContextFiles also reads the global agent directory first, then climbs parents until the filesystem root. Codex stops at .git by default and does not hardcode the .MD or CLAUDE.md names.

Read it yourself: In agents_md.rs, search for is_untrusted and for AGENTS_MD_SEPARATOR. An untrusted project should skip the files, and the separator --- project-doc --- should appear only where user-level text switches to project text. Then open resource-loader.ts and compare loadContextFileFromDir with candidate_filenames.

Finished this idea?

Your learning progress stays in this browser.