A good part of what my coding agents make now isn't code. A rollout plan. A comparison of three queue libraries. A migration checklist for a client...
For further actions, you may consider blocking this person and/or reporting abuse
Section 3 is the one that bites me. Draft in Claude Code, a teammate continues in Codex, and Codex happily re-proposes the thing we rejected on day one because the doc says what we decided but not what we threw away.
On Suraj’s question about the brief going stale: what’s worked for me is not writing the brief by hand at all. The session itself already has the rejected options in it, the agent just can’t see the old session. So I keep the history and let the next agent search it when it needs the “why”, instead of trusting a summary someone forgot to update.
How do you handle it when the next agent is a different tool? Same AGENTS.md read by both, or separate?
For the most part put the rules and skills in place. Every session in my case has /wrapup-skill, its purpose is go and look at the documentation (I have ADR, bugs, features etc.,) organized in different folders and reconcile (not just update).
The new session agent when launches understand the context and shows me what is exactly planned for next. If I want to switch between design decisions, bugs etc., I can in that session. My team follows similar standard too, so not much deviation and we do keep them as .md files (Haven't tried switching between Claude or Codex, but the thought is most of these vendors follow similar style where we can port these rules).
That wrap-up skill that reconciles instead of just updating is a smart split. Updating only adds things, while reconciling catches the decisions that quietly stopped being true.
The part I keep tripping on is the “what we threw away” bit. The ADRs hold the decision, but the reason we rejected the alternative usually lives in the chat, and that’s exactly what disappears. Do you put rejected options into the ADR itself, or do you rely on the session for those?
On porting the rules: the content transfers pretty well; the wiring doesn’t. Claude Code and Codex both pick up a Markdown file at the start; Cursor wants its own format. Has your team seen the same rule behave differently across tools?
ADR contains all our decisions records (including options explored and reason for rejection), for the most part agent does this. Later I go and review them.
We didn't experiment with multiple tools at this moment.
That’s the part I’d want to rely on too. The gap I keep hitting: the agent writes the ADR at the end, and the reason for rejecting option B came up in a message twenty turns earlier, so it’s gone by then. Do you ask it to write the rejection when the decision is made, or does it catch them at the end?
Usually when I see the reason I would want in the messages, I explicitly annotate that this needs to go to ADR. Session keeps them in memory until the wrapup skill runs
To your closing question: for us it ended up being a JSONL ledger in the repo, where reviewer verdicts on our agent's reply drafts are recorded round by round next to the draft text. We added it on Sep 12, after the browser step that posts them got blocked and seven drafts plus their first review round existed only in that session's scratch space; the next session would not have known they were there. Now a later session reads which round each draft has passed and which criteria failed, then revises, posts or drops it, and drafts expire after 14 days. It covers your 'Where it stands' line more than 'Ruled out', so for us it sits next to a brief rather than replacing one.
The handoff brief is an interesting idea, especially the part about preserving why an approach was rejected. I've found that knowing what was tried before can be just as important as knowing the current state. How do you keep that brief useful without letting it become another file that nobody updates?
To your closing question: I moved the whole record into a ticket thread. The spec, progress notes, the reviewer's rework notes and the final links are all messages on one ticket, append-only, and the next agent run on that ticket starts by reading the thread. The thing under review is attached there too, so feedback sits next to the version it was about. Your BRIEF.md is the part I don't have. Who rewrites it when the state changes, the agent unprompted or a person asking?
Đúng vấn đề cốt lõi. Em gặp tình huống này liên tục khi review PR do agent sinh ra: quyết định kiến trúc, lý do chọn lib A thay vì B, trade-off giữa consistency vs performance — toàn nằm rải rác trong commit message hoặc file
.mdtrong thư mụcdocs/mà không ai đọc lại.Cách em đang áp dụng (chưa tối ưu nhưng đỡ hơn không):
ARCHITECTURE.mdversioned theo release — searchable, traceable về commit/PR gốc.- [ ]) trong PR, reviewer tick dần khi verify. Merge xong thì checklist đó thành "source of truth" cho on-call.Vẫn còn missing: không có cách nào link ngược từ code (ví dụ: function
enqueue()) tới ADR giải thích tại sao chọn Redis stream thay vì RabbitMQ. Đang nghĩ tới cách embed reference ID vào (site: labagent .tech)anup, "that's a state problem, not an intelligence problem" is the most accurate sentence I've read about ai agents all year.
we often blame the model for forgetting, when the reality is we failed to give it a deterministic memory anchor. your
agants.mdpattern for pinning the shared url and isolating feedback is brilliant.as someone who builds constraint-driven ai tools (often on devices with severe memory limits), i see this feedback loop issue magnified. when context windows are tight or local memory is constrained, you can't afford to feed the agent a sprawling, unstructured chat history. a concise
brief.mdoradr.mdisn't just a best practice; it's a strict necessity to prevent the agent from looping or hallucinating rejected options.regarding the debate in the comments about keeping the brief from going stale: i’ve found that forcing the agent to append a "rejected options & why" block to the brief at the exact moment the decision is made (rather than waiting for a wrap-up skill at the end of the session) yields much higher fidelity. the context is still hot in the prompt, so the reasoning is captured accurately before it evaporates.
fantastic breakdown. the
byagentskill looks like a very pragmatic solution to this exact wiring problem. 🐯📝Thanks for the framing. I work on marketing at BOMTOBE, the team behind orke, so I am asking out of interest rather than from experience with this exact setup.
For the plans and ADRs an agent writes, where does the why end up once the session closes: in the repo, in a ticket, or only in the session transcript? I am curious whether people trust the transcript enough to reopen it later.