A backlog and standards the agent can read

In the lesson on hooks and CI two team rules moved out of a brief and into the project, where every session runs them. The plan for the next change is often still in one person’s notes or in a chat thread, and the review comments that keep coming back are in old pull requests. A new agent session starts without them. In this lesson we move both to a place the agent reads by itself: the spec into the team’s issue tracker, and a repeated review finding into a standards file or a check.

The project is the nightly sales import from the earlier lessons: importer.py adds up the exports of one night and converts every amount to euros with the rates in rates.json. The team wants to import a past night again with the rates of that night, and has a short spec for it.

Put the spec in the tracker

An agent-reachable backlog is the team’s specs and tickets, kept in its tracker, where people and agents can both read and update them. The tracker also records which ticket blocks which. A spec in a private note helps one person. The same spec as an issue helps every person on the team and every agent session, because each of them can find it, read it in full, and report on it there.

The spec for the past nights has two parts, and the second needs the first. The importer has to keep the rates of each night before it can import a past night with them. So the spec becomes two issues, each with its own “done when” list, and a link between them. GitHub calls the link “blocked by” on one issue and “blocking” on the other, and it marks a blocked issue with an icon in the issue list and on project boards [1]. The order is then in the tracker, where the next reader sees it, and not only in the head of the person who wrote the spec.

With the GitHub command-line tool, gh, the two issues are two commands. The bodies are the two files issue-rates.md and issue-rerun.md in site/examples/coding-with-agents/backlog-and-standards/ of the course repository. --blocked-by takes the number of the issue that must be done first [1]. The second command below assumes the first issue got number 1. Put the number of your first issue in its place if it differs.

gh issue create --title "Keep the rates of each night" --body-file issue-rates.md
gh issue create --title "Import a past night with its own rates" --body-file issue-rerun.md --blocked-by 1

If gh issue create --help doesn’t list --blocked-by, your gh is older than the feature. Update it, or set the link on the issue page in the browser, under Relationships in the sidebar.

In another tracker, look for the same two parts, perhaps under other names: a ticket with a body, and a link type for “this one waits for that one”. Use the link type. A person reads a sentence in the body such as “do this after the rates one”, but only a link lets the tracker mark the issue as blocked.

Checkpoint · multi-choice

What can a new session find on its own?

Which of these can a new agent session in the project use without anyone pasting text into it? Select two.

Select exactly 2.

The spec, written as an issue in the team's trackerThe spec, kept in the notes app on the lead's laptopA "blocked by" link from the second issue to the firstThe order of the two parts, agreed in last week's callThe spec you pasted in full into last week's session

CheckHintSkip

Let the agent read it from the command line

The agent reaches the tracker through the same command-line tool. The vendor guide for Claude Code recommends command-line tools as the way to work with outside services that costs the least context, names gh for GitHub, and suggests that the agent read the --help of a tool it doesn’t know yet [2]. These are the commands the agent needs here:

gh issue list
gh issue view 2
gh issue view 2 --json blockedBy,blocking

gh issue list shows the open issues. gh issue view shows one issue in full, and its output has a “Blocked by” row and a “Blocking” row when a link is set. With --json and the fields blockedBy and blocking, the same links come back as JSON [1].

The brief then names the tracker as the source of the work, and nobody pastes the spec. The transcript below is illustrative and doesn’t record a specific model’s words.

Prompt (illustrative, not a recorded transcript)

The open issues in this repository are the backlog. Use gh issue list and gh issue view to find the open issue that can start now, because its blockers are closed or it has none. Tell me its number, its title, and what it blocks. Don’t change any issue yet.

Response

The repository has two open issues. Issue 2, “Import a past night with its own rates”, is blocked by issue 1. Issue 1, “Keep the rates of each night”, has no blocker and blocks issue 2. So issue 1 is the one to start. Its “done when” list asks for rates/2026-09-14.json to be read for that night, and for a night without a rates file to be rejected.

The commands run with the credentials you give the tool. If those are your own login, the agent has your rights in every repository you can reach. It can close issues and change labels there. Give the agent only the rights it needs. Reading issues and adding comments is enough for most work. If your tracker lets you make a token with fewer rights, use one for the agent. In Claude Code you can also run the session in Manual mode. Claude Code then asks you before most shell commands, and you read each gh command before it runs. From version 2.1.283, a session started in a terminal starts in auto mode by default, so you choose Manual mode on purpose with claude --permission-mode default [3].

Checkpoint · scenario

The agent started the issue that has to wait

The agent says: “Issue 2 is open and nothing blocks it, so I am starting there.” You know issue 2 needs issue 1 first. What do you do?

Tell the agent in this session that the rerun waits for the rates issue, and let it start again.Write the order of the two issues in your own notes, so that you can correct the agent next time.Set a "blocked by" link from the rerun issue to the rates issue, then ask the agent again.Tell the agent to always take the open issue with the lowest number, since it is usually the first.

DecideHintSkip

Write a repeated finding down once

Review comments have a second problem. A reviewer writes “use Decimal for money, not float” on one pull request, and two weeks later writes the same comment on the next one, for a change another session wrote. The comment is in the old pull request, where no new session reads it. The memory page for Claude Code names two moments to write a rule down that fit here: the agent repeats a mistake, or a code review turns up a fact about the project that the agent was missing [4].

A standards file is the team’s list of coding rules that no tool checks. Human reviewers and agent reviewers read the same file, and check a change against it. A short STANDARDS.md for the import could start like this:

# Standards

Rules that no check enforces. Reviewers block a change that breaks one
of these, and mark every other style point as a suggestion.

## Errors

- An error message names the file it is about, and the row when there is one.
  For example: "nights/2026-09-15/store-03.csv, row 12: 5 fields, expected 4".

For an agent to read the file in every session, the project instructions point at it. A line @STANDARDS.md in CLAUDE.md imports the file, and Claude Code loads it at launch together with CLAUDE.md [4]. A reviewer gets the same file through a link in the pull request template or the review checklist.

Some findings don’t need a line, because a script can find them. The float comment is one. The hooks and CI lesson showed how a rule that must hold every time becomes a hook or a CI step, and a repeated finding can take the same path. This check flags every call to float( in the files it is given. It is crude on purpose. When the code one day needs a float for something other than money, make the check narrower then.

Example · run it

The finding as a check

The course’s script copies the nightly import and check_money.py to a temporary directory, runs the check the way a CI step would, and prints its exit status. Run it from site/examples/coding-with-agents/backlog-and-standards/ in your clone of the course repository, and compare what you see with the output below.

python3 run_check.py

Output

$ python3 check_money.py importer.py
importer.py:60: money as float, use decimal.Decimal: total = sum(float(amount) * rates[currency] for _, _, currency, amount in rows)
1 finding(s)
exit status 1

Output verified in CI from site/examples/coding-with-agents/backlog-and-standards/run_check.py.

This example isn’t graded. It is a command you run, with output the course checks on every build.

The check exits with status 1, so as a step in the CI job it fails the pull request until the amount goes through Decimal. Once the check is in CI, delete the float line from the standards file if you wrote one there. The check runs on every change, and the file stays a short list of the rules that only a reader can check. That length matters for the agent too: the memory page advises keeping CLAUDE.md under 200 lines, and an imported file loads at launch and takes context the same way [4].

Checkpoint · match

Where does each finding go?

Match each review finding to what the team does with it.

A total that counts one row twice, found for the first timeChoose…Fix it in this change onlyA line in the standards fileA check in the CI jobA suggestion that doesn't block

Error messages that don't name the file, found in a second reviewChoose…Fix it in this change onlyA line in the standards fileA check in the CI jobA suggestion that doesn't block

An amount converted with float(), found in a second reviewChoose…Fix it in this change onlyA line in the standards fileA check in the CI jobA suggestion that doesn't block

A reviewer would name a function differently, and no rule covers namesChoose…Fix it in this change onlyA line in the standards fileA check in the CI jobA suggestion that doesn't block

CheckHintSkip

Block on the file, suggest the rest

The file also changes what a reviewer may block on. Google’s code review guide for reviewers says that on questions of style, the team’s style guide decides, and a style point the guide doesn’t cover is the reviewer’s personal preference. It suggests a prefix such as “Nit:” for a small improvement that the author doesn’t have to make [5]. The guide treats design as more than taste, and a bug or a design problem can still block a change. For the conventions of the code, the standards file is the team’s style guide. A broken rule from the file, or a failed check, blocks the change. Every other style point is a suggestion.

That gives an agent reviewer a clear brief. Ask it to review the diff against STANDARDS.md and to mark a style finding as blocking only when it names the rule it breaks. Ask it to write every other style point as a “Nit:”, and to block on a bug as usual. When a reviewer, human or agent, blocks on taste, the author can no longer tell the rules in the file from the preferences, and starts to treat both as optional.

Checkpoint · choice

A blocking finding with no rule behind it

The agent reviewer writes: “Blocking: rename read_rows to parse_rows.” No rule in the file covers names, and nothing else is wrong with the change. What do you do?

Rename the function as the reviewer asks, because the change shouldn't merge while a finding blocks it.Add a naming rule to the standards file now, so that the finding has a rule behind it and can block.Delete the finding from the review, because a point without a rule behind it isn't useful to the author.Treat it as a "Nit:" that the author can take or leave, and remind the reviewer to block on style only for a rule or a check.

CheckHintSkip

Pitfall: The token that could do everything

A team gave its agent the lead’s own login for the tracker, because it was already set up on the machine. One afternoon someone asked the agent to “tidy up the backlog”. It closed thirty issues it judged to be stale, including four that waited on a decision from a customer, and nobody saw it happen until the next planning meeting. The agent needed to read issues and add comments, and the login could close and delete them. Give the agent credentials for what the task needs, and read every command that changes the tracker before it runs.

Exercise

Make a project from the course files and push it to a repository you can delete. From the root of your clone of the course repository, run:

cp -R site/examples/coding-with-agents/observing-and-debugging/nightly ~/backlog-me
cp site/examples/coding-with-agents/backlog-and-standards/issue-rates.md site/examples/coding-with-agents/backlog-and-standards/issue-rerun.md site/examples/coding-with-agents/backlog-and-standards/check_money.py ~/backlog-me/
cd ~/backlog-me
git init --initial-branch=main
git add .
git commit -m "Nightly import with two issue bodies"

Create an empty private repository on GitHub that you can delete afterwards, and push the copy to it, with the address GitHub shows for the new repository in place of <url>. gh auth status tells you whether gh is logged in.

cd ~/backlog-me
git remote add origin <url>
git push -u origin main

Create the two issues with the two gh issue create commands from this lesson, the second one blocked by the first. Then start Claude Code inside ~/backlog-me in Manual mode with claude --permission-mode default, and give it the brief from the transcript. Read each gh command before you approve it. The brief asks for a report only, and gh runs with your own login, which reaches every repository you can reach. So approve only gh issue list and gh issue view, and refuse every other gh command and any git push.

Then turn one finding into a rule. Take a finding that came up in two reviews in your own team, or use the float finding from this lesson. If no script can find it, write it as a line in a STANDARDS.md and add @STANDARDS.md to a CLAUDE.md. If a script can find it, make it a check, such as python3 check_money.py importer.py as a step in a CI job like the one in the hooks and CI lesson. Commit the result on a branch and open a pull request for it. Twenty minutes is enough for the issues and a line in the standards file. The CI step takes longer, and it is extra.

A good result has two issues with a “blocked by” link between them, an agent that named the rates issue as the one to start without anyone pasting the spec, and one finding that is now a line in the standards file or a check that fails on the mistake. Delete the repository when you are done. Then answer one question: which review comment have you written more than once this month, and where would it go?

Stretch: Then brief the agent to review its own next change against STANDARDS.md, to mark a style finding as blocking only when it names a line of the file, to write every other style point as a "Nit:", and to block on a bug as usual. Check that it does.

Recap

1. An agent-reachable backlog keeps specs and tickets in the team’s tracker, where people and agents both read them. A spec in a private note or a chat reaches nobody else.
2. Record the order of the work with the tracker’s own links. GitHub marks an issue that is blocked by another, and gh issue view shows the links [1].
3. The agent reads the tracker through a command-line tool, which costs little context [2]. Give it the rights the task needs, and read each command that changes the tracker before it runs.
4. When a review finding comes back, write it in the standards file that human and agent reviewers both read, and import that file into the project instructions [4]. When a script can find the mistake, make it a check and delete the line.
5. Reviewers block on a rule in the file, a failed check or a real defect, and mark other style points as suggestions [5].

You can now

• Keeps specs and tickets where the team and the agent can both reach them
• Turns recurring review findings into written standards or automated checks

Mark lesson finishedI know this, skip it

Habit

The next time you write a review comment you have written before, stop and add it to the standards file, or to a check, before you send the review.

References

1. GitHub. Creating issue dependencies. GitHub documentation. Reference. GitHub docs creating-issue-dependencies
2. Anthropic. Best practices for Claude Code. Claude Code documentation. Reference. Claude Code best practices
3. Anthropic. Choose a permission mode. Claude Code documentation. Reference. Claude Code permission modes
4. Anthropic. How Claude remembers your project. Claude Code documentation. Reference. Claude Code memory
5. Google. Code Review Developer Guide. Google Engineering Practices Documentation. Reference. Google eng-practices