152 lines
3.6 KiB
Plaintext
152 lines
3.6 KiB
Plaintext
# ${PROJECT_NAME} — Claude Code Instructions
|
|
|
|
> **Project:** ${PROJECT_DESCRIPTION}
|
|
> **Repository:** ${REPO_URL}
|
|
|
|
## Session Protocol
|
|
|
|
### Starting a Session
|
|
```bash
|
|
git pull --rebase
|
|
```
|
|
|
|
### Ending a Session
|
|
```bash
|
|
git pull --rebase
|
|
git add -A
|
|
git commit -m "feat: <what changed>"
|
|
git push
|
|
```
|
|
|
|
## Conditional Documentation Loading
|
|
|
|
**Read the relevant guide before starting work:**
|
|
|
|
| Task Type | Guide |
|
|
|-----------|-------|
|
|
| Bootstrapping this project | `~/.config/mosaic/guides/bootstrap.md` |
|
|
| Orchestrating autonomous tasks | `~/.config/mosaic/guides/orchestrator.md` |
|
|
| Code review | `~/.config/mosaic/guides/code-review.md` |
|
|
| Frontend development | `~/.config/mosaic/guides/frontend.md` |
|
|
| Backend/API development | `~/.config/mosaic/guides/backend.md` |
|
|
| Authentication/Authorization | `~/.config/mosaic/guides/authentication.md` |
|
|
| Infrastructure/DevOps | `~/.config/mosaic/guides/infrastructure.md` |
|
|
| QA/Testing | `~/.config/mosaic/guides/qa-testing.md` |
|
|
|
|
## Technology Stack
|
|
|
|
| Layer | Technology |
|
|
|-------|------------|
|
|
| **Frontend** | ${FRONTEND_STACK} |
|
|
| **Backend** | ${BACKEND_STACK} |
|
|
| **Database** | ${DATABASE_STACK} |
|
|
| **Testing** | ${TESTING_STACK} |
|
|
| **Deployment** | ${DEPLOYMENT_STACK} |
|
|
|
|
## Repository Structure
|
|
|
|
```
|
|
${PROJECT_DIR}/
|
|
├── CLAUDE.md # This file
|
|
├── AGENTS.md # Agent-specific patterns and gotchas
|
|
├── docs/
|
|
│ ├── scratchpads/ # Per-issue working documents
|
|
│ └── templates/ # Project templates (if any)
|
|
├── ${SOURCE_DIR}/ # Application source code
|
|
├── tests/ # Test files
|
|
└── ${CONFIG_FILES} # Configuration files
|
|
```
|
|
|
|
## Development Workflow
|
|
|
|
### Branch Strategy
|
|
- `main` — Production-ready code
|
|
- `develop` — Integration branch (if applicable)
|
|
- `feat/<name>` — Feature branches
|
|
- `fix/<name>` — Bug fix branches
|
|
|
|
### Building
|
|
```bash
|
|
${BUILD_COMMAND}
|
|
```
|
|
|
|
### Testing
|
|
```bash
|
|
${TEST_COMMAND}
|
|
```
|
|
|
|
### Linting
|
|
```bash
|
|
${LINT_COMMAND}
|
|
```
|
|
|
|
### Type Checking
|
|
```bash
|
|
${TYPECHECK_COMMAND}
|
|
```
|
|
|
|
## Quality Gates
|
|
|
|
**All must pass before committing:**
|
|
|
|
```bash
|
|
${QUALITY_GATES}
|
|
```
|
|
|
|
## Issue Tracking
|
|
|
|
All work is tracked as issues in the project's git repository.
|
|
|
|
### Workflow
|
|
1. Check for assigned issues before starting work
|
|
2. Create scratchpad: `docs/scratchpads/{issue-number}-{short-name}.md`
|
|
3. Reference issues in commits: `Fixes #123` or `Refs #123`
|
|
4. Close issues only after successful testing
|
|
|
|
### Labels
|
|
Use consistent labels: `epic`, `feature`, `bug`, `task`, `documentation`, `security`, `breaking`
|
|
|
|
### Commits
|
|
```
|
|
<type>(#issue): Brief description
|
|
|
|
Detailed explanation if needed.
|
|
|
|
Fixes #123
|
|
```
|
|
Types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`
|
|
|
|
## Code Review
|
|
|
|
### Independent Review (Automated)
|
|
After completing code changes, run independent reviews:
|
|
|
|
```bash
|
|
# Code quality review (Codex)
|
|
~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted
|
|
|
|
# Security review (Codex)
|
|
~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted
|
|
```
|
|
|
|
**Fallback:** If Codex is unavailable, use Claude's built-in review skills.
|
|
|
|
### Review Checklist
|
|
See `~/.config/mosaic/guides/code-review.md` for the full review checklist.
|
|
|
|
## Secrets Management
|
|
|
|
**NEVER hardcode secrets.** Use `.env` files (gitignored) or a secrets manager.
|
|
|
|
```bash
|
|
# .env.example is committed (with placeholders)
|
|
# .env is NOT committed (contains real values)
|
|
```
|
|
|
|
## Multi-Agent Coordination
|
|
|
|
When multiple agents work on this project:
|
|
1. `git pull --rebase` before editing
|
|
2. `git pull --rebase` before pushing
|
|
3. If conflicts, **alert the user** — don't auto-resolve data conflicts
|