DEV Community: Shayan Araghi

Research, Plan, Implement: A Workflow That Keeps AI Agents Accurate

Shayan Araghi — Tue, 18 Aug 2026 13:00:00 +0000

The Problem: Context Rot

Have you ever had to stop an AI agent halfway through a task to correct it? Work with AI agents long enough and you'll see a pattern: the longer a session runs, the worse the output gets.

Every input you give the agent and every output it produces gets appended to the context window. Nothing leaves. By the time you're fifty messages deep, the agent is re-reading abandoned approaches, stale file contents, and corrections you made an hour ago.

The fix isn't a better prompt. It's less context.

The Core Rule

Keep the context window small. Two habits will keep your AI agent from hallucinating:

Delegate to subagents. Subagents do the heavy reading in their own context and return only the summary.
Clear between phases. Once a phase produces a file, you no longer need the context that led to it.

I aim to stay under 40% context usage in the main agent.

Research → Plan → Implement

I picked up this workflow from a HumanLayer talk, and it's the most reliable setup I've used. There are three phases, each ending in a markdown file, with a context clear between each.

Research — the agent writes a research doc, then clears.
Plan — the agent writes a plan doc, then clears.
Implement — the agent executes the plan.

The main agent never needs to remember the previous phase, because the previous phase wrote it down. All it needs is the conclusion.

Research

The research phase answers how something works today. For example: Describe how the payments flow works end to end. Look carefully at the API endpoint implementations.

The main agent spins up parallel subagents to figure it out. From HumanLayer's repo, I found three subagents to be the most useful:

codebase-locator — finds where things live
codebase-analyzer — explains how a component works
codebase-pattern-finder — finds existing patterns to model the new work after

The best part about using subagents is that you can point them at a cheaper model. Mine run Sonnet while the orchestrator runs Opus.

Plan

The plan phase creates the exact steps needed to build the feature. It lists which files to touch, which lines, and what exactly needs to change. It runs codebase-locator and codebase-analyzer in parallel, then writes the plan.

You can pass in an existing research doc. The agent will reference it but still verify it, in case the code has drifted since it was written.

Plans are only as good as the requirements you give them. Agents don't have the full context, so they fill the gaps by assuming what you need. I've found those assumptions rarely match what the app actually needs. Write out the edge cases and the exact behavior you want.

I'd also add a fourth subagent: context-locator, which finds prior research relevant to your task. My research docs overlap a lot, and pulling in older ones produces noticeably better plans.

What a plan doc looks like

A real plan runs long — usually a few hundred lines across several phases. Here's the shape of one, for a made-up feature: adding rate limiting to an API.

# Rate Limiting Implementation Plan

## Current State Analysis

- **All routes are unthrottled** — `src/api/router.ts:34-58`
- **Redis is already available** for session storage, so no new infra is needed
  — `src/lib/redis.ts:12`
- **Auth middleware runs before routing**, which is where a limiter would slot
  in — `src/middleware/auth.ts:20-45`

**Key gaps:**
- No rate-limiting library installed (verified: absent from `package.json`)
- No per-user identifier available on unauthenticated routes

## Desired End State

- Authenticated requests are limited to 100/min per user; unauthenticated to
  20/min per IP.
- Exceeding the limit returns `429` with a `Retry-After` header.
- Limits are configurable per route without code changes.

### Key Discoveries
- The existing Redis client is created per-request, which will not work for a
  shared counter — it needs a singleton — `src/lib/redis.ts:12-19`
- Health-check endpoints must stay unthrottled or the load balancer will mark
  instances unhealthy — `deploy/lb-config.yaml:22`

## What We're NOT Doing

- No distributed quota syncing across regions.
- No admin UI for adjusting limits (config file only).
- No billing-tier-based limits — that's a follow-up.

---

## Phase 1: Shared Redis Client

### Changes Required

#### 1. Convert the Redis client to a singleton
**File**: `src/lib/redis.ts`
**Changes**: Export one shared connection instead of constructing per request.

```ts
let client: RedisClient | null = null;

export function getRedis(): RedisClient {
  if (!client) client = createClient({ url: process.env.REDIS_URL });
  return client;
}
```

#### 2. Update existing call sites
**Files**: `src/middleware/auth.ts:28`, `src/api/session.ts:15`
**Changes**: Replace `new RedisClient(...)` with `getRedis()`.

### Success Criteria

#### Automated Verification:
- [ ] Unit tests pass: `npm test`
- [ ] Type check passes: `npm run typecheck`

#### Manual Verification:
- [ ] Sessions still persist across requests after the singleton change.

**Implementation Note**: Pause after Phase 1 for confirmation — this touches
session handling, so a regression here breaks login.

A few things in there matter more than they look:

File paths carry line numbers. src/api/router.ts:34-58 means the agent actually read the file instead of guessing at its shape.
Gaps are verified, not assumed. "verified: absent from package.json" tells you it checked rather than inferred.
Key Discoveries catch the things that break you. The per-request Redis client and the health-check exemption are exactly the details you'd discover painfully in review — or in production.
"What We're NOT Doing" is the scope fence. This is the section that stops an agent from cheerfully building an admin UI you never asked for.
Success criteria split automated from manual. The agent can run the first list itself and knows to hand you the second.
Pause points are explicit. Risky phases say so and stop for confirmation.

Implement

The implement phase reads the plan in full before touching anything. If it can't see how the pieces fit together, it should stop and validate rather than guess. It then executes the plan, checking in when something is ambiguous.

Read the Files. Actually Read Them.

This is the step people skip.

I've lost count of the research and plan docs that assumed the wrong thing. Catching those errors early saves you the bug fixes you'd otherwise do later.

It's the same rule as any development cycle: catch errors early. Read every research and plan file before moving to the next phase.

When to Skip the Research Phase

The instinct is to always run research → plan. That's not always the best process.

Small feature? Skip the research and write the plan. A research doc just gives context-locator more to look through and burns tokens.
Need to understand an unfamiliar area? Start with research. Future features in that area can reuse the doc.
Large feature? Write a research doc per area of your app — how payments work, what the end-to-end user flow looks like, and so on. Then a task like Add a new payment method already knows where to look.

Where to Store the Files

For a monorepo, I use thoughts/shared/ with research/ and plans/ subfolders, and I commit every file I create to keep the context alongside the code.

The exception is large teams, where a lot of people may be committing their files. In that case, I'd keep them local and share when needed.

Let me know how this works for you!

Sources

A Second Brain Your AI Agent Can Read: Obsidian + Claude

Shayan Araghi — Sat, 08 Aug 2026 15:00:00 +0000

Background

There are so many details we need to remember in life. Recently I've been
working on a legacy project that was written years ago with no maintainers left.
I've had to continuously dig through thousands of lines of my own notes just to
remember how a particular piece of the application works. Sifting through notes
to find one detail takes time I'd rather spend architecting and building.

AI agents change that. They make it much easier to store and retrieve
information you wrote down days, months, or years ago.

What is Obsidian

Obsidian is a note-taking app that stores everything as
plain markdown files. It lets you organize and structure your notes in a
flexible way, and because the files are plain text on disk, anything that can
read a directory can read your notes, including an AI agent.

For projects, I use Obsidian as my personal documentation: how a system works,
why a decision was made, what the process flows are. Think of it as a second
brain. Everything lives in one place.

The part that makes it work with an agent isn't the app, it's the linking.
Obsidian lets you create bidirectional links between notes with
[[Note Name]]. That turns your vault from a pile of files into a graph you can
hand an agent a single entry point to.

How I structure my files

Obsidian is flexible enough that there are a dozen reasonable ways to set this
up. Here's mine, but you can adapt it to whatever fits your style.

I keep two folders. MOC stands for Map of Content, and holds one file per
topic named <Topic Name> - MOC. Permanent Notes holds everything else. Every
time I create a note related to a topic, I link it in both directions:
[[<Permanent note name>]] in the MOC, and [[<Topic Name> - MOC]] in the
note.

The following files are examples:

vault/
├── MOC/
│   └── Legacy Payments API - MOC.md
└── Permanent Notes/
    ├── Payments API - Endpoints.md
    ├── Payments API - Webhook Retry Logic.md
    ├── Payments API - Settlement Flow.md
    └── Payments API - Architecture Decisions.md

And the MOC itself stays deliberately thin:

# Legacy Payments API - MOC

Legacy service handling card settlement.

## Reference

- [[Payments API - Endpoints]]
- [[Payments API - Webhook Retry Logic]]

## Design

- [[Payments API - Settlement Flow]]
- [[Payments API - Architecture Decisions]]

This is the whole trick. Instead of pointing an agent at a folder and hoping it
reads the right things, you point it at one file that tells it exactly which
notes matter and how they relate. You control the context window instead of
letting the file system decide it for you.

Connecting your agent to the vault

There's no plugin or integration to set up here. Because Obsidian notes are just
markdown files on disk, any agent that can read your file system can read your
vault.

My workflow is simple: I open Claude at the vault root and tell it to read a
specific MOC file.

Read MOC/Legacy Payments API - MOC.md and the notes it links to.

Or paste the full path in directly if you'd rather not think about where you
launched from.

The reason to open at the root rather than inside MOC/ is that the links point
outward. Your MOC lives in one folder and every note it references lives in
another, so an agent scoped to MOC/ has to reach outside its working directory
to follow them. Depending on your setup that means approving access every time.

Using an agent with the MOC

When I start researching a topic, I create the MOC first and give the agent the
path to it.

On the legacy project, that meant creating Legacy Payments API - MOC, then
working through the codebase asking Claude to document the API endpoints, the
business logic, and the process flows — with each one landing as its own
permanent note and each one linked back to the MOC. I wrote my architecture
documents into the vault too, so I can reference them later instead of
reconstructing the reasoning from scratch.

Once the MOC has some substance, it becomes the entry point for everything else.
When I need a plan for a new feature, the prompt is roughly:

Read MOC/Legacy Payments API - MOC.md and every note it links to. Then write
an implementation plan for adding partial refunds to the settlement flow. Flag
anything in the existing notes that contradicts the change.

Tips to work efficiently

Two things went wrong for me before this settled into something useful.

Agents write far too much. Ask for documentation on a service and you'll get
a small book. It becomes too dense for a human to actually read. The more text
the agent has to go through, the more likely it is to hallucinate something that
isn't in there.

The fix is the most important habit when working with AI agents: proofread what
the agent wrote before you save it. It's tempting to trust Claude to write notes
and then never look at them, but a proofreading pass lets you cut the sections
you'll never need. Every paragraph you delete now is context the agent doesn't
have to process later.

Notes drift out of sync. New information surfaces in conversation and never
makes it into the vault, so the next time you read the note it's wrong. Keeping
notes short is what makes them maintainable. If you can scan the section headers
of a note in ten seconds, you'll actually update it. Long notes are far less
likely to get updated.

What doesn't belong in the vault

The instinct when an agent is doing the writing is to let it document
everything, because it's free. But every line it writes is a line you have to
proofread and a line it has to read on every future run.

The thing to cut first is code detail. You don't need a note listing every
parameter on every method, or a walkthrough of what each function does line by
line. That information is already documented by the code itself.

Keep the vault at the level the code can't tell you. Why the retry logic backs
off the way it does. What the endpoints are actually doing at a high level. The
reasoning behind an architecture decision nobody wrote down at the time. That's
the stuff you can't reconstruct from source.

Two more things I've learned to leave out.

The first is the agent's own reasoning. When Claude works through a problem it'll
often narrate how it got there, what it ruled out, what it checked, and why it
landed where it did. That's useful to read in the moment, but it becomes noise
in a document.

The second is anything that has an authoritative source somewhere else — framework
docs, library references, the ticket describing the requirement, the Slack thread
where a decision got made. Copying those into the vault creates a second copy
that starts going stale immediately. Link to them instead.

The main idea is to keep your notes concise and at a high level to stop the AI
agent from hallucinating.

A decent test: if the information already lives somewhere authoritative — the
repo, the ticket, the docs — you don't need to duplicate it. Write down the part
that only exists in your head.

Summary

Documentation is hard to write and harder to keep current, and on a legacy
project with no maintainers that gap is where all your time goes. Pairing an
agent with Obsidian doesn't remove the work. You still proofread and keep things
in sync. What it changes is the kind of work. Instead of scanning your notes to
find information, you're scanning them to verify it, and that's a much
simpler job.

Let me know how it works for you.

Deploying to AWS Lightsail with a Docker image from ECR

Shayan Araghi — Mon, 27 Jul 2026 00:10:19 +0000

Lightsail is a good home for a single small container: flat pricing, bandwidth included, and none of the VPC/security-group ceremony of EC2. The one rough edge is pulling a private image from Amazon ECR, because a standard Lightsail instance can't authenticate to ECR the way EC2 can. This post walks the whole path.

The pipeline we're building:

docker build ──push──> ECR (private repo) ──pull──> Lightsail instance ──run──> container

What you'll need

An AWS account and the AWS CLI installed locally.
Docker installed locally (to build) and on the Lightsail box (to run).
A Dockerfile that produces a runnable image. If you're deploying a Next.js app, a standalone output image works well.

1. Create the ECR repository

ECR is a private Docker registry. Create one repository per image:

aws ecr create-repository \
  --repository-name project-name \
  --region us-east-1

Note the repositoryUri in the output — it looks like:

<account-id>.dkr.ecr.us-east-1.amazonaws.com/project-name

You'll use that URI everywhere below. Export it to save typing:

export ECR_URI=<account-id>.dkr.ecr.us-east-1.amazonaws.com/project-name
export AWS_REGION=us-east-1

2. Build the image locally

First, the Dockerfile. This is a multi-stage build for a Next.js app using output: "standalone" — the first stage installs dependencies and builds, the second copies only the traced runtime files into a slim image that runs as a non-root user:

FROM node:24-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:24-alpine
WORKDIR /app
ENV NODE_ENV=production
ENV PORT=3000
ENV HOSTNAME=0.0.0.0

# Standalone output ships only the traced files needed to run the server.
# public and .next/static are not included by default and must be copied in.
# --chown makes the files writable by the non-root user so Next.js can write
# its runtime cache to /app/.next/cache.
COPY --from=builder --chown=node:node /app/public ./public
COPY --from=builder --chown=node:node /app/.next/standalone ./
COPY --from=builder --chown=node:node /app/.next/static ./.next/static

# Pre-create the cache dir owned by node; Next.js writes here at runtime.
RUN mkdir -p .next/cache && chown -R node:node .next

USER node
EXPOSE 3000
CMD ["node", "server.js"]

This assumes next.config sets output: "standalone". Without it, the .next/standalone directory won't exist and the COPY steps will fail.

Now build for the architecture your Lightsail instance runs. Most Lightsail plans are x86_64, so if you're on an Apple Silicon Mac you must cross-build or the image won't run:

docker build --platform linux/amd64 -t project-name .

Tag it with the ECR URI so it can be pushed. A latest tag is all you strictly need:

docker tag project-name:latest ${ECR_URI}:latest

3. Push to ECR

ECR uses short-lived tokens for docker login. The AWS CLI can fetch one and pipe it straight into Docker:

aws ecr get-login-password --region $AWS_REGION \
  | docker login --username AWS --password-stdin ${ECR_URI}

Then push:

docker push ${ECR_URI}:latest

Note the braces: ${ECR_URI}:latest, not $ECR_URI:latest. Depending on your shell, the bare form can mis-parse the :latest — you'll see the tag swallowed in the output (e.g. a repo name ending in ...showcaseatest) and the push will fail with repository does not exist. ${ECR_URI} makes the variable boundary explicit and avoids it.

4. Create the Lightsail instance

Create an instance (Amazon Linux 2023 keeps the Docker install simple), SSH in, and install Docker:

sudo dnf install -y docker
sudo systemctl enable --now docker
sudo usermod -aG docker ec2-user
# log out and back in so the group change applies

5. The wrinkle: authenticating Lightsail to a private ECR repo

On EC2 you'd attach an IAM role to the instance (an instance profile) and the AWS CLI would pick up credentials automatically from instance metadata — no keys on the box. Standard Lightsail instances don't support instance-profile roles, so that clean path isn't available.

The practical path is an IAM user with read-only ECR access, whose access keys live on the instance:

In the IAM console, create a new IAM user (e.g. lightsail-ecr-pull).
Attach the AWS-managed AmazonEC2ContainerRegistryReadOnly policy to the user.
Create an access key for that user — you'll get an access key ID and a secret. This is what the instance uses to authenticate.

Then configure the CLI on the instance with that user's keys:

aws configure   # paste the pull-only user's access key + secret

The takeaway from the earlier question stands: on Lightsail you can't fully eliminate the IAM user the way an EC2 instance role does — you can only keep what it's allowed to do small. AmazonEC2ContainerRegistryReadOnly limits it to pulling images, so if the keys leak that's the whole blast radius. Rotate them periodically.

6. Pull and run on the instance

Log Docker in to ECR (same token dance as the push, run on the instance):

aws ecr get-login-password --region us-east-1 \
  | docker login --username AWS --password-stdin \
    <account-id>.dkr.ecr.us-east-1.amazonaws.com

Pull and run:

docker pull <account-id>.dkr.ecr.us-east-1.amazonaws.com/project-name:latest

docker run -d \
  --name web \
  --restart unless-stopped \
  -p 80:3000 \
  <account-id>.dkr.ecr.us-east-1.amazonaws.com/project-name:latest

One more step before this is reachable: open the port in Lightsail's firewall. Lightsail instances have their own IPv4 firewall that only allows SSH (22) and HTTPS (443) by default — port 80 is closed, so the container above is running but unreachable. In the console, go to the instance's Networking tab and, under IPv4 Firewall, add a rule for HTTP / TCP / 80. (This is separate from any OS-level firewall; the Lightsail rule is the one that bites first.)

Now open the instance's public IP in a browser — you should see the app.

The ECR login token expires after 12 hours. That only affects pulling, so it's a non-issue for a running container. When you deploy a new version, just re-run the get-login-password | docker login step first.

7. Give it a static IP

One thing is still missing before this is a real deployment: the instance's public IP changes on reboot. Lightsail's default public IP is dynamic — stop/start the instance and it changes, breaking any DNS record pointing at it. In the console, go to Networking → Create static IP, attach it to your instance, then point your domain's A record at that static IP. A static IP is free while it's attached to a running instance (you're only billed if you reserve one and leave it unattached), so there's no reason not to.

8. Deploying a new version

The update loop is: build → push → pull → replace.

# locally
docker build --platform linux/amd64 -t ${ECR_URI}:latest .
docker push ${ECR_URI}:latest

# on the instance
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin <account-id>.dkr.ecr.us-east-1.amazonaws.com
docker pull <account-id>.dkr.ecr.us-east-1.amazonaws.com/project-name:latest
docker stop web && docker rm web
docker run -d --name web --restart unless-stopped -p 80:3000 <account-id>.dkr.ecr.us-east-1.amazonaws.com/project-name:latest

Is this worth it over building on the box?

Pushing through ECR shines when you want the build to happen off the server — in CI, on your laptop, anywhere with more resources than a small instance — and the instance only ever pulls a finished artifact. If instead you're happy to git clone and docker build on the box, you skip ECR (and the IAM user) entirely. Pick based on where you want the build to live, not on hosting alone.

There's a cost angle too: the cheapest Lightsail tiers (the 512 MB / 1 vCPU plans) often can't run docker build at all — a Next.js build will exhaust the RAM and get OOM-killed mid-build. Building elsewhere and pulling a finished image from ECR sidesteps that entirely: pulling and running a prebuilt image is far lighter than compiling one, so ECR is what lets you host on these less-expensive instances instead of paying for a bigger box just to survive the build.