Spexso

Appearance

AI-Assisted Development with Claude Code ​

Claude Code is the productivity multiplier. But unstructured AI use produces unstructured code. The key is giving Claude the right context. That's what CLAUDE.md is for.

The CLAUDE.md File ​

Every repository has a CLAUDE.md file at its root. This is the most important file in the repo for AI-assisted development. It tells Claude Code everything it needs to know about the project: the architecture, the patterns, the conventions, the do's and don'ts. Think of it as the project's brain-dump for AI.

markdown
# Project: {project-name}

## Overview
{One paragraph describing what this application does, who it's for,
and which SAP system it extends.}

## Architecture
- Framework: SAP CAP (Node.js / Java)
- Database: SAP HANA Cloud
- Frontend: SAP Fiori Elements / UI5 Freestyle
- Auth: SAP XSUAA
- Deployment: SAP BTP Cloud Foundry / Kyma

## Project Structure
{Tree of key directories with descriptions}

## Key Patterns & Conventions
- We use {pattern} for {reason}
- Service handlers follow {convention}
- Error handling: {approach}
- Naming: {rules}

## Do NOT
- Never use inline SQL, always use CQL
- Never hardcode tenant IDs
- Never skip input validation on external APIs
- Do not add npm packages without approval

## Testing
- Unit tests: Jest with {patterns}
- Integration tests: {approach}
- Test data: fixtures in /test/data/

## Common Commands
- `npm run dev` — start local with hybrid profile
- `npm test` — run full test suite
- `npm run deploy` — build & deploy MTA

## Related Specs
- Current work: {link to GitLab issue}
- API contract: {link to wiki page}

How Each Role Uses Claude Code ​

  • Sales / Product Scout — Use cases: Draft customer proposals from opportunity specs. Generate competitive feature comparisons. Summarize customer feedback into structured requests. Create business case documents from raw notes.
  • Functional Consultants — Use cases: Generate BDD acceptance criteria from user stories. Create test scenario matrices. Validate spec completeness against checklist. Draft data model descriptions. Generate process flow descriptions from requirements.
  • Developers — Use cases: Generate service implementations from specs. Write unit and integration tests. Refactor legacy code with guardrails. Write MR descriptions. Debug issues with full context. Generate CDS models from data requirements.
  • Tech Lead — Use cases: Review MRs with AI-assisted analysis. Generate architecture decision records. Identify code smells across repos. Create and maintain CLAUDE.md files. Design API contracts.

AI Development Rules ​

The AI Contract

Every team member signs off on these rules before using Claude Code on production codebases.

  • Rule 1: AI generates, humans validate. Never merge AI-generated code without understanding every line. If you can't explain it, you can't ship it.
  • Rule 2: CLAUDE.md is mandatory. Every repo must have an up-to-date CLAUDE.md. If Claude doesn't know your project, it will hallucinate patterns. Keep it current.
  • Rule 3: Spec first, AI second. Don't start a Claude Code session without a spec or issue link. AI without context is just an expensive random generator.
  • Rule 4: Tag AI involvement. Use the ai:: labels on issues. Use conventional commit messages: feat(ai-assisted): add leave request handler. This lets us measure AI's impact.
  • Rule 5: Review AI code harder. AI-generated code tends to look "correct" but can miss edge cases, security concerns, or project-specific patterns. Review it with more scrutiny, not less.
  • Rule 6: Learn from AI. When Claude suggests a pattern you haven't seen, research it. Claude is a learning tool. The goal is to make the team smarter, not more dependent.
  • Rule 7: TypeScript first. All new modules and files MUST be written in TypeScript. Only use JavaScript when modifying existing JavaScript modules. New functionality → new files in TypeScript.

Four of these rules are enforced in code, not just prose: a per-task time budget (budgets.perTaskMinutes, default 30) stops a build task that overruns instead of letting it grind silently; the issue's size:: label dials which model runs the tester/builder for that task (small task → fast model, big task → strong model); the project's .spexso/rules/doctrine.md is injected into every agent session automatically via a Claude Code hook; and // spexso-debt: markers left in code are harvested into a committed .spexso/debt.md ledger so debt stays visible instead of buried in comments.