Team Development Guidelines
After reading this document, follow the step-by-step daily workflow in the Daily Git & Development Workflow guide.
This document defines the mandatory workflow for all developers on the TradeEntry project. Read it completely before writing a single line of code. Skipping any section is not allowed.
Purpose
This document defines the mandatory workflow, coding process, AI usage rules, Git workflow, and documentation standards for all developers working on the TradeEntry project.
The goal is to ensure:
- Consistent architecture
- Domain understanding before implementation
- Controlled AI-assisted development
- Maintainable codebase
- Reduced debugging workload
- Stable releases
1. Core Principles
All developers must internalize these before anything else:
- We are building a structured trading platform — not a prototype.
- Business logic consistency is more important than coding speed.
- Existing architecture must be respected — understand it before changing it.
- AI tools assist development but do NOT replace engineering judgment.
2. Mandatory Development Workflow
Every task MUST follow this exact workflow in order.
1. Read documentation
↓
2. Understand business logic
↓
3. Create task markdown file
↓
4. Review existing implementation
↓
5. Prepare AI prompts
↓
6. Implement feature
↓
7. Test thoroughly
↓
8. Update documentation
↓
9. Create Pull Request (PR)
Skipping any step is NOT allowed. If you are unsure about a step, stop and ask — do not skip it.
3. No Direct Coding Rule
Developers must NOT start coding immediately after receiving a task.
Before writing any code you must:
- Read all related documentation pages
- Understand the domain logic the feature touches
- Identify existing reusable modules, components, or services
- Verify the full API flow end-to-end
- Confirm the correct architecture pattern to follow
The most expensive bugs in this project came from developers who started coding before understanding what already existed.
4. Mandatory Task Documentation
Before writing any code, every developer MUST create a task file at:
docs/docs/developer/tasks/<task-name>.md
No coding is allowed before this file exists and is committed.
Use this exact structure:
# Task Name
## Objective
What this task achieves and why it is needed.
## Business Logic
The trading/domain logic this feature implements or touches.
Never assume — document what you confirmed.
## Existing Flow
Which existing files, endpoints, and components are involved.
Describe the current behaviour before your change.
## Files Allowed to Modify
List every file you are permitted to change for this task.
## Files NOT Allowed to Touch
List files that must not be changed (with reason).
## UI Flow
Step-by-step user journey through the UI for this feature.
## API Flow
Request → endpoint → service → DB → response chain.
## AI Prompt Used
The exact prompt(s) given to Claude Code for this task.
## Risks
What could go wrong. What existing functionality could be affected.
## Validation Checklist
- [ ] No console errors
- [ ] No API errors
- [ ] Existing features unaffected
- [ ] Edge cases handled
- [ ] TypeScript types valid
5. Business Logic First
Developers must fully understand the following before implementing:
- The trading logic the feature involves
- The intended workflow behaviour (from the user's perspective)
- The user's intention (what problem they are solving)
- How the existing architecture already handles related flows
Never assume domain behaviour.
If logic is unclear:
- Ask questions — document the answers
- Document all assumptions explicitly in the task file
- Seek clarification from the senior developer before proceeding
Domain references: Market Profile, Neo Wave, ORB Tests, Domain Knowledge
6. Reuse Existing Architecture
Before creating anything new, verify whether it already exists.
Check in this order:
- Extend existing code (preferred)
- Reuse existing patterns
- Create new implementation only if steps 1 and 2 are impossible
Before creating a new component, service, utility, hook, or API endpoint — ask Claude:
"Does this functionality already exist in the project?
Show me all related existing implementations."
7. File Creation Policy
Developers MUST NOT create:
- Random
.pyfiles without architectural justification - Random
.tsxfiles without checking existing pages/components - Duplicate service files
- Duplicate utility functions
Every new file must have:
| Requirement | Description |
|---|---|
| Clear purpose | One responsibility, clearly named |
| Proper naming | Follow existing conventions in that folder |
| Documented justification | Explained in the task markdown file |
If in doubt — extend an existing file. Do not create a new one.
8. AI-Assisted Development Rules
AI tools (Claude Code) are allowed and encouraged but must follow strict rules.
Required instruction — include this at the start of every AI session
/tradeentry
This loads all project rules, patterns, and hard-won lessons into Claude's context. Every session must start with this. No exceptions.
Additional instruction to include before every AI coding task
Analyze existing architecture first.
Reuse existing components, services, and hooks.
Do not introduce new patterns unless necessary.
Follow the exact patterns used in [reference file].
What AI must NOT do in this project
- Redesign existing architecture
- Introduce new state management approaches
- Create duplicate API layers
- Add new dependencies without approval
- Generate speculative abstractions or over-engineered solutions
Always tell Claude which existing file to follow as a pattern. Vague prompts produce code that doesn't fit the project.
9. AI Prompt Logging
All major AI prompts must be documented in:
docs/docs/prompts/
Each prompt record must contain:
- Purpose — what the prompt was trying to achieve
- Prompt used — exact text given to Claude
- AI response summary — what Claude produced
- Implementation decision — what was actually used and why
This prevents inconsistent architecture across developers. If two developers independently solve the same problem differently, it creates conflicts. Logging prompts ensures knowledge is shared across the team.
See existing examples: Coding Prompts, Debugging Prompts
10. Coding Standards
Backend (FastAPI / Python)
| Rule | Detail |
|---|---|
| Type hints | All function parameters and return types must be typed |
| Modular routers | One router file per feature group in app/api/ |
| Schema validation | All request/response bodies use Pydantic models |
| No business logic in routes | Routes call services — logic lives in service layer |
| Centralised configuration | All paths and env vars go through app/config.py |
| Log messages | ASCII only — no Unicode characters (→ … etc.) |
| Module invocation | Always python -m nseeod.module from backend/ |
Frontend (React / TypeScript)
| Rule | Detail |
|---|---|
| Functional components only | No class components |
| Proper typing | No any types — use proper TypeScript interfaces |
| Reusable components | UI components go in src/components/, not inside pages |
| No duplicated state logic | Extract shared state into hooks in src/hooks/ |
| Folder structure | Follow existing structure — pages in src/pages/ |
| API calls | All HTTP calls go through src/services/api.js only |
| No direct axios calls | Never import axios directly inside a component |
11. Git Workflow
Direct commits to main branch are NOT allowed.
Your machine (feature branch)
↓
git push origin feature/name
↓
Pull Request (PR) on GitHub
↓
Senior Developer Review
↓
Merge to main
12. Branch Naming Convention
| Type | Format | Example |
|---|---|---|
| New feature | feature/short-name | feature/order-entry |
| Bug fix | fix/short-name | fix/ami-unicode-error |
| Refactor | refactor/short-name | refactor/api-cleanup |
| Hotfix | hotfix/short-name | hotfix/login-error |
| Documentation | docs/short-name | docs/api-reference-update |
13. Pull Request Rules
Every PR must include all of the following:
| Section | Content |
|---|---|
| Objective | What this PR achieves |
| Business logic summary | The domain logic implemented |
| Files changed | Complete list with reason for each |
| Screenshots | Required for any UI change |
| API changes | New/modified endpoints with request+response |
| AI prompts used | Link to or paste the prompt log |
| Testing summary | What was tested and how |
A PR without all sections will be rejected without review.
14. Small PR Rule
Large PRs are difficult to review and introduce risk.
Developers must:
- Keep PRs focused on a single task
- Separate unrelated changes into separate PRs
- Never combine a feature + refactor + bug fix in one PR
- Never perform large refactors without explicit senior approval
Rule of thumb: if a PR touches more than 5 files, split it up.
15. Mandatory Testing
Before submitting any PR, the developer must verify:
- No browser console errors
- No API errors (check Network tab)
- All existing features still work (smoke test)
- Edge cases handled (empty state, error state, loading state)
- TypeScript:
npm run buildpasses with zero errors infrontend/ - Python: no import errors, module runs correctly
- Docs:
npm run buildpasses indocs/if docs were changed
16. Documentation Updates
Every important feature must update the relevant docs.
| Change type | Update here |
|---|---|
| New user-facing feature | docs/docs/user-guide/ |
| New API endpoint | docs/docs/developer/api.md |
| Architecture change | docs/docs/developer/architecture.md |
| New backend module | docs/docs/developer/backend.md |
| New frontend pattern | docs/docs/developer/frontend.md |
| Bug fix | docs/docs/prompts/debugging-prompts.md |
| Any major change | docs/docs/versions/ (version history) |
Documentation is not optional. It is part of development.
17. Version History
All major changes must be documented in:
docs/docs/versions/
Each version file must include:
- Added features
- Bug fixes
- Architecture changes
- Migration notes (if DB or API changed)
See existing examples: v1.0, v1.1
18. Domain Knowledge
Before working on any of the following areas, read Domain Knowledge first:
- Trading logic (order flow, position management)
- Market Profile (TPO, POC, VAH, VAL)
- Neo Wave / Elliott Wave
- NSE data structures (bhav copies, F&O contracts, OI)
- Intraday systems (ORB, expiry day behaviour)
No assumptions should be made about trading terminology. If a term is unfamiliar, look it up in the docs before building anything that uses it.
19. Architecture Protection Rule
The following actions require explicit senior developer approval before starting:
- Redesigning any existing architecture
- Replacing or upgrading a framework or major library
- Introducing a new state management system
- Adding a new database table or modifying an existing schema
- Duplicating an API layer that already exists
- Bypassing an existing flow (e.g. calling the DB directly from a component)
When in doubt — ask first. Refactor later with approval.
20. Final Principle
Code quality is not measured by:
- Number of files created
- Complexity of abstractions
- How quickly it was written
Code quality is measured by:
- Clarity — can anyone read and understand it?
- Consistency — does it follow the same patterns as the rest?
- Maintainability — can it be changed safely in 6 months?
- Domain correctness — does it actually solve the right problem?
- Architectural alignment — does it fit the existing system?
Golden Rule
Understand business logic first. Code second.
Quick Reference Card
# Start every Claude Code session with:
/tradeentry
# Run the project locally
cd backend && venv\Scripts\activate && uvicorn app.main:app --reload
cd frontend && npm run dev
cd docs && npm start
# Before any PR — check TypeScript
cd frontend && npm run build
# Before any PR — check docs
cd docs && npm run build
# NSE data sync (only as module, from backend/)
cd backend
python -m nseeod.downloadbhav
Next Step
You have read the rules. Now follow them every day.
👉 Daily Git & Development Workflow →
Every git command, every PR step, every commit format — all in one place.
This document is maintained by the senior developer.
Questions? Read it again. Then ask Coding Agent with /tradeentry loaded. Then ask the senior dev.