Harness engineering (TypeScript) · Chapter 9 of 23

Project files

By the end of this chapter you can find a repository's project file (AGENTS.md) the way coding assistants do, put it in the system prompt, load a folder's own file only when the agent first works in that folder, cap a file that has grown too big for the window, and say, with numbers from the suite, what the project file is worth. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: Context
  • 4 tasks
  • TypeScript
  • In the all labs plan

The first 2 chapters of Harness engineering (TypeScript) are free. This one comes with the all labs plan.

Why you need this

Chapter 8's prompt knows Hisaab because you typed Hisaab into its config: the language, the folders, the test command. That works for one repository and one engineer who knows it. It does not know the things only Hisaab's team knows, and T04 needs one of them.

T04's issue: gstAmount(2525, 18) gives 454 paise, and GST rounds half up, so it should be 455. Under chapter 8's written prompt, the model finds gstAmount, and its first fix is the one most JavaScript code would use:

edit_file(src/gst.ts, "return Math.round((basePaise * rate) / 100);"
                   -> "return Math.floor((basePaise * rate) / 100 + 0.5);")
run_command(npm test)                   -> ℹ pass 44, ℹ fail 1
    ✖ gstAmount rounds half up
      AssertionError [ERR_ASSERTION]: credit notes too: round half away
      from zero in integer paise, with roundHalfUp
edit_file(src/gst.ts, the first try -> roundHalfUp(basePaise * rate, 100))
run_command(npm test)                   -> ℹ pass 45

It passes, in 7 steps, because the prompt says to run the tests and the test's message happens to name the right function: Math.floor(x + 0.5) rounds a credit note of -2525 paise at 18% to -454, not -455. Under the one-line prompt nothing runs the tests, the first try stays, and T04 fails. Hisaab's rule is "money is integer paise, rounded with roundHalfUp", and Kabir has said it in every code review for two years. It is written down in one place, which the harness never reads: the project file.

What you build: 4 tasks

Each task has tests. You write the code in the lab's editor and press Check.

  1. Task 1

    load-project.ts: find the project file, put it in the prompt

    Kabir wants the harness to read what the repository says about itself. In load-project.ts, export projectFiles(start: string): string[]: every AGENTS.md from the repository's root down to the folder start, outermost first. The root is the nearest folder, from start upward, with a .git in it; never look above it. No file: an empty array.

    Then export projectPrompt(base: string, start: string): string: the base prompt, then for each file a blank line, # Project file (PATH) with PATH relative to the root (AGENTS.md, src/AGENTS.md), a new line and the file's text. With no file, the base unchanged.

    Under if (import.meta.main), run runAgent on a T01 checkout with projectPrompt(SYSTEM, root) (SYSTEM from ./agent.ts) and print as the last line T01: passed in N steps (or failed).

  2. Task 2

    nested.ts: a folder's own file, loaded on first touch

    A folder can have its own AGENTS.md. In nested.ts, export a class NestedLoader, made with new NestedLoader(root). touch(path), path relative to root: for every folder from just below root down to the path's folder, outermost first, that it has not loaded before, mark it loaded and, if it has an AGENTS.md, take # Project file (PATH), a new line and its text (PATH from the root). Return those blocks joined by a blank line, or null when there is nothing new. The root's own file is already in the prompt (never load it), and a path outside root loads nothing.

    onTool(name, args): for read_file and edit_file, touch(args.path); for any other tool, null. agent.ts's runAgent takes an onTool option and adds what it returns to the system message. The check runs T04 with a src/AGENTS.md that has the rounding rule: the rule must arrive after the first read in src/, and the first fix must be right.

  3. Task 3

    t04-both.ts: T04 without and with the project file

    Nandini wants the project file's worth in numbers. In t04-both.ts, run T04 four times, each on a fresh checkout, in this order: the one-line prompt 'You are a coding agent. Fix the issue.' without and then with the project file (projectPrompt of that prompt), then SYSTEM without and then with it. Grade each one, count its test runs (the run_command calls in result.messages whose arguments have npm test in them), and print:

    T04 written with passed 5 steps tests run: 1

    (the task, one-line or written, without or with, passed or failed, the steps and the test runs, two spaces apart).

  4. Task 4 · interview question

    Interview: size-cap.ts, a project file too big for the window

    Someone pasted the GST guide into AGENTS.md, and the first request is refused. In size-cap.ts, export loadCapped(path, cap): the file's text if it is at most cap tokens (o200k_base); otherwise its first whole lines that fit in cap tokens, then a line [AGENTS.md cut: N of M tokens shown; read the file for the rest] (the file's own name, N the tokens of the kept text, M the whole file's). Then export cappedPrompt(base, start, cap = 1500): projectPrompt's layout with each file through loadCapped.

    Under if (import.meta.main), on a fresh T01 checkout whose AGENTS.md has a new line and docs/gst-guide.md appended, print AGENTS.md: N tokens, run runAgent with projectPrompt(SYSTEM, root) and print uncapped: STOP GRADE N steps (result.stop, passed or failed, the steps, two spaces apart); then on another such checkout, the same with cappedPrompt, as capped: STOP GRADE N steps.

What you will learn

  • What a project file is: how a repository tells every agent its layout, commands and rules.
  • Finding it the way coding assistants do: from the folder the agent starts in, up to the repository's root.
  • Putting it in the prompt, and what it changes on T04 and on the steps of other tasks.
  • Nested files, loaded the first time the agent works in their folder.
  • A size cap, for a project file that has grown too big.

More in Context

Build "Project files" yourself

Hisaab, a Lucknow invoicing startup, wants a coding agent to clear its bug list. You build its harness in TypeScript and score it on twelve tasks. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.

The first 2 chapters of Harness engineering (TypeScript) are free. This one comes with the all labs plan.