local-project-context

Local Project Context

Overview

You run on a local developer machine, not in a CI/CD pipeline. There is no remote runner that will catch your mistakes later — the build and tests you run in your workspace are the only verification that happens before a human sees the result. Treat your workspace as production's last line of defense.

Core principle: Explore before you change; verify in this environment before you claim.

The environment

• Task workspace: each task is worked in a cloned checkout on its own branch. Your working directory is injected into the session context — always use it as the root, never assume paths from another task.
• Live codebase: your changes take effect immediately in the workspace. There is no separate deploy step for verification.
• No inherited state: if you build or test in this workspace, do it from scratch — never assume a prior session left a build artifact, a running server, or a seeded database.

Exploration tools (use before changing code)

Tool	Use for
codebase_search	Concept/semantic search — "where is auth handled"
grep_code	Exact symbol/string — a function name, an error message
get_repo_tree	Structure and file layout of the repository
get_symbol_skeleton	A symbol's signature and outline without its full body
expand_symbol_context	Focused read of a symbol and its surroundings
read_file	Read a file with line numbers — up to 800 lines per call
run_terminal	Build, test, run the app, inspect output

File tools (use instead of the shell for anything touching a file)

Tool	Use for
read_file	Read with line numbers, whole file in one call
edit_file	Replace an exact string; replace_all: true changes every occurrence at once
edit_lines	Replace / insert / delete by line number — add a function, an import, remove a block
write_file	Create a file, or replace one whole
delete_file	Remove a file or directory
move_file	Rename or move

Never cat, sed -n, head, tail, sed -i, rm, mv or a heredoc through the shell. A shell read costs a full agent turn per window; a sed -i is silent about what it matched, so you spend a second turn grepping to find out whether it worked; and a heredoc mangles backticks, quotes and template literals.

Every file tool reports what it did — the number of occurrences changed, the line numbers, the region as it now reads. That is your confirmation. Do not grep or re-read the file to check. One edit is one turn.

In a CLI runtime (Claude Code / Codex / opencode) read_file, edit_file, write_file, run_terminal, grep_code and get_repo_tree are your native Read/Edit/Write/Bash/Grep/Glob — same rules apply.

Find the existing pattern first (the neighboring endpoint, the similar component, the analogous test) and follow it. A parallel convention you invent is a review finding waiting to happen.

Verification (use before every handoff)

The build gate that runs after your run executes exactly the component's required checks — list_component_checks returns them with the local command that reproduces each. Run those commands, not a guessed one. The table below is only the fallback when no checks are mapped:

Stack	Build	Test
Go	go build ./... && go vet ./...	go test ./... (or the affected ./path/...)
Java	./mvnw -q verify / ./gradlew build	(included)
Web	npm run build in the package that holds package.json	npx vitest run or CI=1 npm test — never watch mode
Flutter	flutter analyze	flutter test (a build needs a target: flutter build apk --debug, flutter build web)

Full builds and suites outlast run_terminal's 60s default: pass timeout_seconds (up to 900). Redirect long output to a file and read its tail (mkdir -p /tmp/tt-<task key> && … > /tmp/tt-<task key>/test.log 2>&1; tail -80 /tmp/tt-<task key>/test.log — never a shared fixed path).

If the build or tests do not pass in this run, the task is not ready to move forward — say what failed.

Your role

• Developers: all of the above — explore, edit, build and test the whole stack.
• QA: black-box. Exploration is get_repo_tree, grep_code, read_file only — to find the start command, the port and the route, never the diff, to decide a verdict. The file tools above are still yours for your own scratch work (a fixture, a script), never for product code.
• Architect at code_review: read, never run. The code tools above are for reading the diff and the surrounding code; building or testing it yourself is not your job and not your evidence — the developer's run already did that.

Common Mistakes

• Reasoning about behavior from reading code instead of running it — except at code_review, where reading the diff IS the job.
• Reusing a path or branch name from a previous task's workspace.
• Assuming npm install / go mod download already ran — check, don't assume.

Red Flags

• "It built last time" — build again, now (unless you are the architect: you never build).
• "The server should still be running" — never assume; start it.