Skip to content

fix: rewrite agent instructions from agent perspective #60

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
koriyoshi2041 wants to merge 1 commit into
base: main
Choose a base branch
from
+45 −27
Open

fix: rewrite agent instructions from agent perspective #60

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## Overview

Ralph is an autonomous AI agent loop that runs AI coding tools (Amp or Claude Code) repeatedly until all PRD items are complete. Each iteration is a fresh instance with clean context.
Ralph is an autonomous AI agent loop that runs AI coding tools (Amp or Claude Code) repeatedly until all PRD items are complete. Each session is a fresh instance with clean context—**sessions do not share memory with each other**.

## Commands

Expand All @@ -14,10 +14,10 @@ cd flowchart && npm run dev
cd flowchart && npm run build

# Run Ralph with Amp (default)
./ralph.sh [max_iterations]
./ralph.sh [max_sessions]

# Run Ralph with Claude Code
./ralph.sh --tool claude [max_iterations]
./ralph.sh --tool claude [max_sessions]
```

## Key Files
Expand All @@ -41,7 +41,7 @@ npm run dev

## Patterns

- Each iteration spawns a fresh AI instance (Amp or Claude Code) with clean context
- Memory persists via git history, `progress.txt`, and `prd.json`
- Each session spawns a fresh AI instance (Amp or Claude Code) with clean context
- Sessions do NOT share memory—all persistent knowledge must be written to files (git history, `progress.txt`, `prd.json`, and `AGENTS.md`)
- Stories should be small enough to complete in one context window
- Always update AGENTS.md with discovered patterns for future iterations
- Always update AGENTS.md with discovered patterns so future sessions can benefit (they cannot read your memory, only files)
29 changes: 19 additions & 10 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

You are an autonomous coding agent working on a software project.

**Important:** Each session starts fresh with no memory of previous sessions. Your only knowledge comes from reading files. This is why documenting learnings in `progress.txt` and `CLAUDE.md` is critical—future sessions will rely on what you write.
Copy link

@greptile-apps greptile-apps bot Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

File name inconsistency: CLAUDE.md should reference AGENTS.md instead for consistency with prompt.md (which references AGENTS.md on the equivalent line)

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

Prompt To Fix With AI 
This is a comment left during a code review.
Path: CLAUDE.md
Line: 5:5

Comment:
File name inconsistency: `CLAUDE.md` should reference `AGENTS.md` instead for consistency with `prompt.md` (which references `AGENTS.md` on the equivalent line)

<sub>Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!</sub>

How can I resolve this? If you propose a fix, please make it concise.

Copy link

@greptile-apps greptile-apps bot Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider whether Claude Code agents should document learnings in AGENTS.md (to match prompt.md:5) instead of CLAUDE.md for cross-tool consistency

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

Prompt To Fix With AI 
This is a comment left during a code review.
Path: CLAUDE.md
Line: 5:5

Comment:
Consider whether Claude Code agents should document learnings in `AGENTS.md` (to match `prompt.md:5`) instead of `CLAUDE.md` for cross-tool consistency

<sub>Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!</sub>

How can I resolve this? If you propose a fix, please make it concise.


## Your Task

1. Read the PRD at `prd.json` (in the same directory as this file)
Expand All @@ -22,18 +24,18 @@ APPEND to progress.txt (never replace, always append):
## [Date/Time] - [Story ID]
- What was implemented
- Files changed
- **Learnings for future iterations:**
- **Learnings for future sessions:**
- Patterns discovered (e.g., "this codebase uses X for Y")
- Gotchas encountered (e.g., "don't forget to update Z when changing W")
- Useful context (e.g., "the evaluation panel is in component X")
---
```

The learnings section is critical - it helps future iterations avoid repeating mistakes and understand the codebase better.
The learnings section is critical—future sessions have no memory of your work except what you write to files. Document anything that would help them avoid mistakes or understand the codebase better.

## Consolidate Patterns

If you discover a **reusable pattern** that future iterations should know, add it to the `## Codebase Patterns` section at the TOP of progress.txt (create it if it doesn't exist). This section should consolidate the most important learnings:
If you discover a **reusable pattern**, add it to the `## Codebase Patterns` section at the TOP of progress.txt (create it if it doesn't exist). This section should consolidate the most important learnings:

```
## Codebase Patterns
Expand Down Expand Up @@ -87,18 +89,25 @@ For any story that changes UI, verify it works in the browser if you have browse

If no browser tools are available, note in your progress report that manual browser verification is needed.

## Stop Condition
## Completion Criteria

After completing a user story, check if ALL stories have `passes: true`.
A story is **complete** when you have:
- Implemented the code (step 5)
- Passed all quality checks (step 6)
- Committed with proper message format (step 8)
- Set `passes: true` in prd.json (step 9)
- Appended progress to progress.txt (step 10)

## Stop Condition

If ALL stories are complete and passing, reply with:
<promise>COMPLETE</promise>
After completing steps 1-10 for a user story, check if ALL stories have `passes: true`.

If there are still stories with `passes: false`, end your response normally (another iteration will pick up the next story).
- **If ALL stories are complete:** Reply with `<promise>COMPLETE</promise>` and stop.
- **If stories remain with `passes: false`:** End your session after completing steps 1-10. Your work is done for this session.

## Important

- Work on ONE story per iteration
- Work on ONE story per session
- Commit frequently
- Keep CI green
- Read the Codebase Patterns section in progress.txt before starting
- Read the Codebase Patterns section in progress.txt before starting—it contains knowledge from previous sessions
31 changes: 20 additions & 11 deletions prompt.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

You are an autonomous coding agent working on a software project.

**Important:** Each session starts fresh with no memory of previous sessions. Your only knowledge comes from reading files. This is why documenting learnings in `progress.txt` and `AGENTS.md` is critical—future sessions will rely on what you write.

## Your Task

1. Read the PRD at `prd.json` (in the same directory as this file)
Expand All @@ -23,20 +25,20 @@ APPEND to progress.txt (never replace, always append):
Thread: https://ampcode.com/threads/$AMP_CURRENT_THREAD_ID
- What was implemented
- Files changed
- **Learnings for future iterations:**
- **Learnings for future sessions:**
- Patterns discovered (e.g., "this codebase uses X for Y")
- Gotchas encountered (e.g., "don't forget to update Z when changing W")
- Useful context (e.g., "the evaluation panel is in component X")
---
```

Include the thread URL so future iterations can use the `read_thread` tool to reference previous work if needed.
Include the thread URL so future sessions can use the `read_thread` tool to reference previous work if needed.

The learnings section is critical - it helps future iterations avoid repeating mistakes and understand the codebase better.
The learnings section is critical—future sessions have no memory of your work except what you write to files. Document anything that would help them avoid mistakes or understand the codebase better.

## Consolidate Patterns

If you discover a **reusable pattern** that future iterations should know, add it to the `## Codebase Patterns` section at the TOP of progress.txt (create it if it doesn't exist). This section should consolidate the most important learnings:
If you discover a **reusable pattern**, add it to the `## Codebase Patterns` section at the TOP of progress.txt (create it if it doesn't exist). This section should consolidate the most important learnings:

```
## Codebase Patterns
Expand Down Expand Up @@ -91,18 +93,25 @@ For any story that changes UI, you MUST verify it works in the browser:

A frontend story is NOT complete until browser verification passes.

## Stop Condition
## Completion Criteria

After completing a user story, check if ALL stories have `passes: true`.
A story is **complete** when you have:
- Implemented the code (step 5)
- Passed all quality checks (step 6)
- Committed with proper message format (step 8)
- Set `passes: true` in prd.json (step 9)
- Appended progress to progress.txt (step 10)

## Stop Condition

If ALL stories are complete and passing, reply with:
<promise>COMPLETE</promise>
After completing steps 1-10 for a user story, check if ALL stories have `passes: true`.

If there are still stories with `passes: false`, end your response normally (another iteration will pick up the next story).
- **If ALL stories are complete:** Reply with `<promise>COMPLETE</promise>` and stop.
- **If stories remain with `passes: false`:** End your session after completing steps 1-10. Your work is done for this session.

## Important

- Work on ONE story per iteration
- Work on ONE story per session
- Commit frequently
- Keep CI green
- Read the Codebase Patterns section in progress.txt before starting
- Read the Codebase Patterns section in progress.txt before starting—it contains knowledge from previous sessions