Daily Development Workflow

Mandatory

Every developer must follow this exact 12-step workflow for every task. No shortcuts. No exceptions.

STEP 1 — Pull Latest Code

Before starting any work, sync with the latest codebase.

git checkout main
git pull origin main

Never start a feature branch from stale code. Always pull first — every single day.

STEP 2 — Create Feature Branch

Create a branch whose name describes the feature — not the person doing it.

Correct examples

git checkout -b feature/order-entry
git checkout -b feature/market-profile-grid
git checkout -b feature/backtest-api
git checkout -b fix/ami-unicode-error
git checkout -b refactor/api-cleanup

Wrong examples

git checkout -b john          # ❌ person's name
git checkout -b test          # ❌ vague
git checkout -b newcode       # ❌ meaningless
git checkout -b wip           # ❌ not a feature

Branch naming convention

Type	Format	Example
New feature	`feature/short-name`	`feature/order-entry`
Bug fix	`fix/short-name`	`fix/login-error`
Hotfix	`hotfix/short-name`	`hotfix/ami-crash`
Refactor	`refactor/short-name`	`refactor/api-cleanup`
Documentation	`docs/short-name`	`docs/api-reference`

STEP 3 — Read Documentation

Before writing any code, the developer MUST read the relevant pages in:

http://localhost:3000/docs/developer/

Minimum required reading for every task:

Page	Why
Architecture	Understand how the system is structured
Domain Knowledge	Understand the trading logic involved
Backend Guide	Understand FastAPI patterns to follow
Frontend Guide	Understand React patterns to follow
API Reference	Check if the endpoint you need already exists

If you cannot explain the existing flow of the feature you are building, you are not ready to code it.

STEP 4 — Create Task Documentation

Before writing any code, create a task markdown file:

docs/docs/developer/tasks/<task-name>.md

Copy the template from task-template.md.

Required sections:

Section	Content
Objective	What this task achieves and why
Business Logic	The domain rules this feature implements
Existing Flow	Current behaviour before your change
Files Allowed to Modify	Explicit list — unlisted files must not be touched
Files NOT Allowed	Files that require approval to change
UI Flow	Step-by-step user journey
API Flow	Request → endpoint → DB → response chain
AI Prompt Used	Exact prompt given to Claude Code
Risks	What could break, and your mitigation
Validation Checklist	Must be completed before PR

Required

No coding is allowed before the task file is committed to your branch.

STEP 5 — Analyze Existing Architecture

Before creating any new file, component, service, or API endpoint — verify whether it already exists.

# Ask Claude Code (after /tradeentry is loaded):
"Does this functionality already exist in the project?
Show me all related existing implementations before I build anything."

Priority order

1. Reuse existing code          ← always check first
       ↓  (only if not possible)
2. Extend existing modules      ← add to what's there
       ↓  (only if not possible)
3. Create new implementation    ← last resort only

Checklist before creating anything new:

Searched codebase for similar component / service / endpoint
Checked frontend/src/components/ for reusable UI
Checked frontend/src/services/api.js for existing API method
Checked backend/app/api/ for existing router/endpoint
Checked backend/nseeod/ for existing data pipeline logic

STEP 6 — Use AI Carefully

All AI-assisted coding uses Claude Code with the project skill loaded.

Start every Claude Code session with

/tradeentry

Prefix every coding task with

Analyze existing architecture first.
Reuse existing patterns and modules.
Do not create duplicate logic.
Do not introduce unnecessary abstractions.
Follow the exact pattern used in [reference file].

Rules for AI usage

Do	Do NOT
Tell Claude which file to follow as a pattern	Give vague prompts like "build a button"
Ask Claude to show existing code first	Let Claude redesign the architecture
Log major prompts in `docs/docs/prompts/`	Use AI output without reviewing it
Review every line Claude writes	Accept generated code blindly

STEP 7 — Implement Feature

Rules during implementation:

Make small, focused changes — one responsibility per commit
No unrelated modifications — if you spot another issue, raise a separate task
No random file creation — every new file needs documented justification
No architecture redesign without explicit senior developer approval
All API calls go through frontend/src/services/api.js — never bypass
Log messages in Python must use ASCII only — no → … or Unicode

STEP 8 — Test Thoroughly

Before committing, verify all of the following:

Browser
  ├── No console errors
  ├── No Network tab API errors
  └── Existing features still work (smoke test)

TypeScript
  └── cd frontend && npm run build   →  zero errors

Python
  └── Module runs without ImportError

Edge cases
  ├── Empty state (no data)
  ├── Error state (API fails)
  └── Loading state (slow network)

STEP 9 — Commit Changes

Commit message format

TASK: <task-name>

Purpose:
<one sentence describing what this commit does>

Files:
frontend/src/pages/OrderEntry.tsx
backend/app/api/order.py
docs/docs/developer/tasks/order-entry.md

Rules

One logical change per commit — do not bundle unrelated changes
Always include the task doc file in your first commit
Never commit node_modules/, .env, or credential files
Never commit directly to main

Examples

# Good commits
git commit -m "TASK: order-entry — add validation for lot size"
git commit -m "TASK: order-entry — wire POST /api/orders endpoint"
git commit -m "fix: ami-unicode — replace arrow chars with ASCII"

# Bad commits
git commit -m "stuff"
git commit -m "fix"
git commit -m "wip"
git commit -m "john's changes"

STEP 10 — Push Branch

git push origin feature/order-entry

If pushing for the first time from this branch:

git push -u origin feature/order-entry

STEP 11 — Create Pull Request

Open GitHub and create a PR from your branch into main.

PR must include all of the following

Section	Detail
Objective	One sentence — what does this PR do?
Business Logic Summary	What trading/domain logic was implemented
Files Changed	List every file and what changed in each
Screenshots	Required for any UI change — before and after
API Changes	New or modified endpoints (method, path, request, response)
AI Prompts Used	Paste key prompt or link to `docs/docs/prompts/` entry
Testing Summary	What was tested, how, and result
Task Doc Link	Link to `docs/docs/developer/tasks/<task-name>.md`

PR checklist (complete before requesting review)

A PR with missing sections or an incomplete checklist will be rejected without review.

STEP 12 — Review Before Merge

No developer merges their own PR.

Your Feature Branch
        ↓
   Push to GitHub
        ↓
   Open Pull Request
        ↓
   Senior Developer Reviews
        ↓
   Changes Requested?  →  Fix and push to same branch
        ↓
   Approved
        ↓
   Merge to Main  (done by senior developer)

After merge:

git checkout main
git pull origin main
git branch -d feature/order-entry   # clean up local branch

Important Rules Summary

Never

Commit directly to main
Create random files without documented justification
Skip the task documentation step
Start coding without reading the docs
Merge your own PR
Use vague branch names (test, wip, john)
Add Unicode characters to Python log messages
Call axios directly in React components

Always

Pull main before creating a branch
Create the task file before writing code
Start Claude Code sessions with /tradeentry
Keep PRs small and focused
Test before pushing
Update documentation when behaviour changes

Golden Principle

Understand domain logic first. Implement second.

Code that is written without domain understanding creates bugs that take 10x longer to debug than the feature took to build.

Quick Reference

# Start of day
git checkout main
git pull origin main
git checkout -b feature/your-task-name

# During work
git add <specific-files>
git commit -m "TASK: task-name — what this commit does"

# End of task
git push origin feature/your-task-name
# → Open PR on GitHub

# After PR merged
git checkout main
git pull origin main
git branch -d feature/your-task-name

STEP 1 — Pull Latest Code​

STEP 2 — Create Feature Branch​

Correct examples​

Wrong examples​

Branch naming convention​

STEP 3 — Read Documentation​

STEP 4 — Create Task Documentation​

STEP 5 — Analyze Existing Architecture​

Priority order​

STEP 6 — Use AI Carefully​

Start every Claude Code session with​

Prefix every coding task with​

Rules for AI usage​

STEP 7 — Implement Feature​

STEP 8 — Test Thoroughly​

STEP 9 — Commit Changes​

Commit message format​

Rules​

Examples​

STEP 10 — Push Branch​

STEP 11 — Create Pull Request​

PR must include all of the following​

PR checklist (complete before requesting review)​

STEP 12 — Review Before Merge​

Important Rules Summary​

Never​

Always​

Golden Principle​

Quick Reference​