Apso NestJS 서비스 템플릿에 AGENTS.md, CLAUDE.md, Copilot 지침을 포함해 배포합니다

# AGENTS.md

## Apso TypeScript (NestJS) Service Template: Agent Guidance

This repository is an Apso service template. Coding agents working here must follow Apso rules even when the Apso MCP server is not connected. Read this file before making changes.

## Source of truth

- `.apsorc` is the source of truth for schema, routes, auth, and relationships. Edit `.apsorc`, then regenerate. Do not hand-edit generated output.
- Never edit files under `src/autogen/`. `apso generate` overwrites them. It does not delete stale files, so removed entities can leave orphaned files behind. If you need to remove generated code, delete the file and regenerate.
- Product code goes in `src/extensions/`. Register every extension module in `src/app.module.rest.ts`.
- Never invent `.apsorc` syntax. If a key or shape is not documented at https://docs.apso.ai/rules/ or present in an existing `.apsorc`, do not add it. Ask or check the CLI source instead.

## Relationships

- Define each relationship exactly once in the top-level `relationships` array.
- For inverse relationships, use `bi_directional`. Do not also declare the reverse side separately.
- Duplicate or conflicting relationship declarations cause generation errors or wrong foreign keys.

## Multi-tenancy

- Scope tenant-owned entities with `scopeBy` in `.apsorc`.
- In custom routes under `src/extensions/`, hand-check tenant access until apsoai/cli#156 lands. Do not assume the framework enforces tenant isolation on custom handlers.

## Destructive operations

- Before running or recommending any destructive migration or deploy, state the risk explicitly: what data can be lost, what is irreversible, and what the rollback path is. Do not proceed silently.

## The loop

Run these in order after schema or code changes:

1. `apso schema validate`
2. `apso generate`
3. `npm run build`
4. `apso doctor`

## Commands

- Migrate: `apso migrate`
- Dev: `apso dev`
- Deploy: `apso deploy`

## Directory layout

```
.apsorc                     # source of truth
src/autogen/                # generated, do not edit
src/extensions/             # product code
src/app.module.rest.ts      # register extension modules here
```

## Route override trick

To disable a generated route without editing `src/autogen/`, declare the route in `.apsorc` with `"http": false`. The generator will skip emitting the HTTP handler, and you can implement it in `src/extensions/` instead.

## Traps

- UUID primary keys must use `@PrimaryGeneratedColumn('uuid')`. Do not use `@PrimaryGeneratedColumn()` without the type, or you get integer IDs.
- Table names that collide with SQL reserved words break migrations. Rename the entity or set an explicit table name.
- Enum columns need an explicit `values` array in `.apsorc`. Missing values produce broken generated types.
- Index every `ManyToOne` column. Unindexed foreign keys cause slow queries and failed reviews.

## MCP tools (when connected)

`design_schema`, `validate_schema`, `scaffold_api`, `setup_auth`, `start_dev_server`, `deploy_api`, `diagnose`, `report_issue`, and the `apso://current-schema` resource. These mirror the CLI commands above. When MCP is not connected, use the CLI directly.

## Reference

- Rules: https://docs.apso.ai/rules/

---

# CLAUDE.md

See [AGENTS.md](./AGENTS.md) for full guidance. The two most expensive mistakes:

1. Never edit `src/autogen/`. It is overwritten on `apso generate`. Put product code in `src/extensions/` and register it in `src/app.module.rest.ts`.
2. Define each relationship exactly once in the top-level `relationships` array. Use `bi_directional` for the inverse. Do not declare both sides.

---

# .github/copilot-instructions.md

Follow [AGENTS.md](../AGENTS.md). Top rules:

- `.apsorc` is the source of truth. Never invent its syntax.
- Never edit `src/autogen/`. Product code goes in `src/extensions/`, registered in `src/app.module.rest.ts`.
- Define each relationship exactly once in `relationships`. Use `bi_directional` for the inverse.
- Scope tenant entities with `scopeBy`. Hand-check tenant access in custom routes until apsoai/cli#156.
- State destructive migration/deploy risk before acting.
- Loop: `apso schema validate`, `apso generate`, `npm run build`, `apso doctor`.

---

## PR note

The Apso CLI clones this template at tag `v2.0.0`. Shipping these guidance files requires a new tag on this repo and a pin bump in apsoai/cli. Until then, agents using the CLI will not see these files.

## Verification performed

- Commands checked against `apso-cli/src/commands/`: `schema validate`, `generate`, `migrate`, `dev`, `deploy`, `doctor`.
- MCP tool list checked against `apso-cli/src/commands/mcp/serve.ts`: `design_schema`, `validate_schema`, `scaffold_api`, `setup_auth`, `start_dev_server`, `deploy_api`, `diagnose`, `report_issue`, `apso://current-schema`.
- Paths `src/autogen/` and `src/extensions/` confirmed against this template.
- https://docs.apso.ai/rules/ resolves.
- `.cursor/rules/apso.mdc` not committed; deleted if present.