jbourdon/social-media
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: moving towards agentic development
Some checks failed
Backend CI/CD / build_and_deploy (push) Has been cancelled
Details
Frontend CI/CD / build_and_deploy (push) Has been cancelled
Details

Browse Source
This commit is contained in:
Jonathan Bourdon
2026-04-24 21:12:26 -04:00
parent df3e602015
commit b6eb692c27
179 changed files with 2880 additions and 866 deletions
Download Patch File Download Diff File Expand all files Collapse all files

601
docs/LLM_DEVELOPMENT_WORKFLOW.md
View File

@@ -1,593 +1,20 @@
# LLM Development Workflow
## Purpose
This document defines how to use coding agents such as Codex, Claude Code, ChatGPT, or similar tools on this repository without losing architectural coherence over time.
This document is kept as a compatibility pointer for older references.
The core rule is simple:
The current agentic workflow now lives in:
- `docs/AGENTIC_WORKFLOW.md`
- `docs/DEVELOPMENT_WORKFLOW.md`
- `docs/ARCHITECTURE.md`
- `docs/CONVENTIONS.md`
- `docs/FEATURES/`
- `docs/TASKS/`
- `docs/PROMPTS/`
- `docs/DECISIONS/`
Core rule:
> The repository is the source of truth. The chat is only a temporary execution surface.
Coding agents should not rely on long conversation history to understand the product, architecture, or current task. Important context must live in versioned files inside the repository.
## Why This Workflow Exists
LLM coding tools are very strong at creating an initial project or implementing isolated changes. They become less reliable when the work shifts from greenfield generation to incremental product engineering.
The common failure mode is this:
1. The first prompt creates a large amount of useful code.
2. Later prompts become increasingly specific and corrective.
3. The agent starts forgetting prior decisions, duplicating patterns, inventing architecture, or changing unrelated files.
4. Most of the work becomes re-explaining context instead of shipping features.
This does not mean the tools are useless. It means the workflow must change.
Early-stage prompting can be broad. Mature product work must be driven by stable docs, scoped tasks, acceptance criteria, and reviewable diffs.
## Operating Model
Use coding agents as fast implementation partners, not as autonomous product owners.
Agents should:
- read repository documentation first;
- understand the current task before editing;
- propose a small implementation plan;
- make minimal, reviewable changes;
- preserve existing architecture and conventions;
- report risks, assumptions, and validation steps.
Agents should not:
- use chat history as the primary source of truth;
- invent product behavior when docs are missing;
- perform broad rewrites during a feature task;
- silently change unrelated files;
- mix backend, frontend, database, UX, and refactoring work without a scoped plan.
## Repository Documentation Model
The repository should contain a small set of durable documents that agents always consult.
Recommended structure:
```text
docs/
PRODUCT.md
ARCHITECTURE.md
CONVENTIONS.md
DECISIONS.md
BACKLOG.md
LLM_DEVELOPMENT_WORKFLOW.md
tasks/
TASK-001-example.md
TASK-002-example.md
AGENTS.md
```
### `AGENTS.md`
`AGENTS.md` is the entry point for coding agents.
It should tell agents:
- how to work in this repo;
- what docs to read first;
- how the backend and frontend are structured;
- what commands to run;
- what rules are non-negotiable;
- how to validate work before finishing.
This file should stay concise enough that agents actually follow it.
### `docs/PRODUCT.md`
Defines the product from the user's perspective.
Include:
- what the product is;
- target users;
- major workflows;
- important UX principles;
- feature boundaries;
- what the product explicitly does not do yet.
Use this file to prevent agents from inventing product behavior.
### `docs/ARCHITECTURE.md`
Defines the technical structure.
Include:
- backend architecture;
- frontend architecture;
- module boundaries;
- authentication model;
- data ownership;
- routing model;
- state management model;
- API integration patterns.
Use this file to prevent agents from inventing new architecture for each task.
### `docs/CONVENTIONS.md`
Defines repeatable implementation patterns.
Include:
- C# style and backend endpoint conventions;
- FastEndpoints patterns;
- EF Core migration rules;
- Vue component conventions;
- Pinia store conventions;
- API client usage;
- validation and error handling patterns;
- testing expectations;
- naming conventions.
Use this file to reduce code style drift.
### `docs/DECISIONS.md`
A lightweight architecture decision log.
Each entry should capture:
- date;
- decision;
- context;
- consequences.
Example:
```md
## 2026-04-23 — Runtime frontend config is centralized
Decision: Frontend runtime configuration must be accessed through `frontend/src/config.js`.
Context: Direct `import.meta.env` reads scattered across feature code make configuration harder to audit.
Consequence: New frontend code should import config from `frontend/src/config.js` instead of reading env variables directly.
```
Use this file to prevent agents from revisiting settled choices.
### `docs/BACKLOG.md`
A human-readable backlog of possible future work.
Use this for ideas, improvements, bugs, and deferred refactors.
Important rule:
> If an agent sees an adjacent problem that is outside the current task, it should add or suggest a backlog item instead of fixing it opportunistically.
### `docs/tasks/TASK-xxx.md`
Task files are the LLM-friendly equivalent of Jira tickets.
They are not just backend tickets. A product feature is usually fullstack and should describe backend, frontend, UX behavior, data model, validation, and acceptance criteria.
The task file should be specific enough that a fresh agent can implement it without reading a long chat thread.
## Task File Template
Use this template for implementation tasks.
```md
# TASK-000 — Short Feature Name
## Status
Draft | Ready | In Progress | Done | Blocked
## Objective
Describe the user-visible or technical outcome in 1-3 sentences.
## Product Context
Explain why this exists and where it fits in the product workflow.
## Scope
- What this task includes.
- Keep this list concrete.
## Out of Scope
- What this task explicitly must not include.
- Add adjacent ideas here to prevent scope creep.
## Existing References
Agents must inspect these before implementation:
- `docs/PRODUCT.md`
- `docs/ARCHITECTURE.md`
- `docs/CONVENTIONS.md`
- relevant existing backend files
- relevant existing frontend files
## Backend Requirements
### API Contract
Endpoint:
- `METHOD /api/example`
Request:
```json
{
"example": "value"
}
```
Response:
```json
{
"id": "string"
}
```
### Validation
- Rule 1
- Rule 2
### Data / Persistence
- Entity changes, if any.
- DbContext/module affected, if any.
- Migration required: yes/no.
### Security / Authorization
- Authentication required: yes/no.
- Roles or workspace access rules.
## Frontend Requirements
### Route / Screen
- Route: `/app/example`
- View file: `frontend/src/views/app/ExampleView.vue`
### Components
- `ExampleForm.vue`
- `ExampleList.vue`
### State Management
- Pinia store used or created.
- Existing store actions to reuse.
### API Integration
- Existing API client usage.
- Expected loading, success, and error behavior.
### UX Behavior
- Empty state.
- Loading state.
- Validation display.
- Toasts or inline errors.
- Navigation after success, if any.
## Files Likely Involved
Backend:
- `backend/...`
Frontend:
- `frontend/...`
Docs:
- `docs/...`
## Acceptance Criteria
- User can complete the intended workflow.
- Backend validates invalid input correctly.
- Frontend displays loading and error states correctly.
- Existing auth, workspace scoping, and refresh behavior are preserved.
- Build passes.
## Validation Plan
Backend:
- `cd backend && dotnet build Socialize.Api.csproj`
- Additional manual or automated checks.
Frontend:
- `cd frontend && npm run build`
- Additional manual route/store checks.
## Risks / Edge Cases
- Risk 1
- Risk 2
## Open Questions
- Question 1
```
## Feature Definition: Fullstack by Default
A feature should normally be defined across these dimensions:
1. Product workflow: what the user is trying to accomplish.
2. UX behavior: screens, states, feedback, errors, navigation.
3. Frontend implementation: routes, components, stores, API calls.
4. Backend implementation: endpoints, validation, persistence, authorization.
5. Data model: entities, migrations, ownership boundaries.
6. Acceptance criteria: what must be true before the task is done.
7. Validation plan: commands and manual checks.
Avoid defining features as backend-only unless the task is explicitly backend-only.
## Recommended Agent Workflow
Use this sequence for non-trivial changes.
### 1. Prepare or update the task file
Create a `docs/tasks/TASK-xxx.md` file before asking an agent to implement a feature.
The task can be rough at first, but it must state:
- objective;
- scope;
- out of scope;
- backend requirements, if any;
- frontend requirements, if any;
- acceptance criteria.
### 2. Start a fresh agent thread per task
Do not run an entire project through one endless chat.
Use one thread for one task or one small group of tightly related subtasks.
### 3. Ask for analysis before implementation
Default prompt:
```text
Read AGENTS.md and the relevant docs first.
Then read docs/tasks/TASK-000-short-name.md.
Do not edit files yet.
Summarize the task, identify the relevant backend and frontend files, list risks, and propose a minimal implementation plan.
```
### 4. Implement one bounded step at a time
Default prompt:
```text
Implement only step 1 from the plan.
Keep the diff minimal.
Do not refactor unrelated code.
Do not change public behavior outside this task.
At the end, summarize changes and list validation steps.
```
### 5. Review the diff
The repository owner reviews:
- scope creep;
- architectural drift;
- duplicated code;
- inconsistent UI behavior;
- unsafe auth or workspace scoping changes;
- broken conventions.
### 6. Validate
Run the relevant commands from `AGENTS.md` and the task file.
Minimum expected validation:
- backend build for backend changes;
- frontend build for frontend changes;
- affected user flow checked manually when UI behavior changes.
### 7. Update docs if the task changed architecture or product behavior
If implementation creates a durable decision, update `docs/DECISIONS.md`.
If implementation changes structure, update `docs/ARCHITECTURE.md`.
If implementation changes conventions, update `docs/CONVENTIONS.md`.
If implementation changes user-facing behavior, update `docs/PRODUCT.md`.
## Prompt Patterns
### Planning Prompt
```text
You are working in an existing repository.
First read:
- AGENTS.md
- docs/PRODUCT.md
- docs/ARCHITECTURE.md
- docs/CONVENTIONS.md
- docs/DECISIONS.md
- docs/tasks/TASK-000-short-name.md
Do not edit files yet.
Return:
1. summary of the task;
2. relevant existing files;
3. backend impact;
4. frontend impact;
5. risks and ambiguities;
6. minimal implementation plan;
7. validation plan.
```
### Implementation Prompt
```text
Implement the task from docs/tasks/TASK-000-short-name.md.
Rules:
- follow AGENTS.md;
- follow docs/ARCHITECTURE.md and docs/CONVENTIONS.md;
- keep the diff minimal;
- do not refactor unrelated code;
- preserve auth, workspace scoping, token refresh, and runtime config patterns;
- if you discover missing requirements, stop and report them instead of inventing behavior.
At the end, provide:
- files changed;
- summary of behavior added;
- validation performed;
- validation still needed;
- risks or follow-up items.
```
### Frontend-Only Prompt
```text
Implement only the frontend part of docs/tasks/TASK-000-short-name.md.
Do not modify backend code.
Use existing routes, stores, API client, UI framework, and runtime config conventions.
Preserve loading, error, empty, and success states described in the task.
```
### Backend-Only Prompt
```text
Implement only the backend part of docs/tasks/TASK-000-short-name.md.
Do not modify frontend code.
Follow the existing FastEndpoints, validation, module, DbContext, and migration conventions.
Preserve auth and workspace scoping rules.
```
### Review Prompt
```text
Review the current diff against:
- AGENTS.md
- docs/ARCHITECTURE.md
- docs/CONVENTIONS.md
- docs/tasks/TASK-000-short-name.md
Look specifically for:
- scope creep;
- architectural drift;
- broken frontend state patterns;
- broken backend module boundaries;
- auth or workspace scoping regressions;
- missing loading/error states;
- missing validation;
- missing tests or manual checks.
Do not edit files. Return findings only.
```
## Rules for Frontend Work
Frontend changes must be explicit in the task.
A frontend task should identify:
- route or screen;
- components to create or modify;
- Pinia stores involved;
- API calls involved;
- loading state;
- error state;
- empty state;
- success feedback;
- navigation behavior;
- role/access behavior;
- responsive or layout expectations, if relevant.
Agents must not invent a new frontend architecture for a single feature.
They should reuse:
- existing Vue patterns;
- existing Vuetify/Tailwind conventions;
- existing Pinia stores where appropriate;
- existing Axios client;
- existing router guards;
- existing toast/error patterns.
## Rules for Backend Work
Backend changes must respect module boundaries.
A backend task should identify:
- endpoint route and method;
- request and response shape;
- validation rules;
- module ownership;
- DbContext affected;
- migration requirement;
- authorization rules;
- workspace scoping rules;
- expected errors.
Agents must not couple module DbContexts or bypass existing auth/security helpers.
## Handling Ambiguity
When a requirement is unclear, agents should not silently invent behavior.
Preferred behavior:
1. State the ambiguity.
2. Propose the safest default.
3. Keep implementation narrow.
4. Add an open question or backlog item if needed.
For small ambiguities that do not affect architecture or product behavior, the agent may choose the safest existing pattern and document the assumption.
For large ambiguities, the agent should stop before implementation.
## Handling Refactors
Refactors should be separate tasks unless they are strictly required for the current feature.
If a refactor is needed, the task should state:
- why the refactor is necessary;
- what files are in scope;
- what behavior must remain unchanged;
- how to validate no regression occurred.
Agents should not do opportunistic cleanup in unrelated files.
## Handling Backlog Items
When an agent notices an issue outside scope, it should not fix it by default.
It should report it as:
```md
Suggested backlog item:
- Title:
- Reason:
- Affected files:
- Risk if ignored:
```
The repository owner can then decide whether to create a task.
## Definition of Done
A task is done when:
- implementation matches the task file;
- scope and out-of-scope boundaries were respected;
- relevant backend and/or frontend validation passed;
- user-facing behavior was manually checked when applicable;
- docs were updated if durable behavior or architecture changed;
- remaining risks or follow-up items were explicitly listed.
## Practical Mental Model
Use this model:
- `AGENTS.md` tells the agent how to behave.
- `docs/PRODUCT.md` tells the agent what the product is.
- `docs/ARCHITECTURE.md` tells the agent how the system is shaped.
- `docs/CONVENTIONS.md` tells the agent how to write code here.
- `docs/DECISIONS.md` tells the agent what choices are already settled.
- `docs/BACKLOG.md` stores ideas that are not current work.
- `docs/tasks/TASK-xxx.md` tells the agent what to do now.
The more this information lives in the repo, the less each new prompt has to reconstruct the project from memory.
For new work, create or update a feature spec in `docs/FEATURES/`, create a small task in `docs/TASKS/<feature>/`, and ask the agent to implement only that task.