AGENTS.md@presets/lang/en/base git:20261104.b145f8cA

Immutable. This exact content never changes and is served at /api/v1/blob/f606da16a53df031.

# AGENTS.md — {{PROJECT_NAME}}

This file is the **single source of truth (SSOT)** that AI agents (Claude Code, Codex, Antigravity)
follow when working in this repository. It is the project brain. No separate `CLAUDE.md`/`GEMINI.md` pointer files are shipped —
Claude Code (v2.1.277+), Codex and Antigravity (agy) all read this file natively.

This file must be **self-contained** — the P0/P1 tiers below are readable here without loading any
other file. The only `@` import allowed here is the memory index (see "Memory path override" below):
harnesses that expand imports auto-load the index, and the rest read it as a path pointer.

> If you add a `CLAUDE.md` (or `CLAUDE.local.md`), Claude Code **stops reading this file** (fallback,
> not merge). If you really need one, make its first line `@AGENTS.md`.

**Personal layer**: instructions that differ per person (communication style, commit rules, machine setup)
do not go in this file — put them in a root `AGENTS.<NAME>.md`. `.claude/scripts/personal-layer.sh on <NAME>`
adds that file to Claude Code (`CLAUDE.local.md`), Codex (`AGENTS.override.md`) and agy
(`.agents/rules/personal-<name>.md`) and keeps the generated files out of commits via `.git/info/exclude`.
A personal layer only **adds** to this file — on conflict, this file wins. (#92)
If the root holds any `AGENTS.<NAME>.md`, **the first reply of every session asks who the user is** (options: each file's
`<NAME>`, plus "none of these"). Once answered, run `.claude/scripts/personal-layer.sh use <NAME>` (or `use none`) as a
standalone command. Follow no personal instructions before that — even when the layer is on and its text is already in context.
The `.claude/hooks/personal-gate.sh` hook enforces this: it injects the question at session start and on every prompt, blocks
every tool except question tools and `use` until answered, then loads that person's file into context and blocks edits to
other people's personal files (Claude Code `settings.json`, Codex `.codex/hooks.json`, agy `.agents/hooks.json`). Without the
hooks the rule still holds — before the first reply, always list the root `AGENTS.*.md` with a tool (skip `AGENTS.override.md`,
a Codex artifact). (#94)

## Response language

- Reply to the user (conversation, reports, questions) **in the language the user writes in**. Keep code, commands, identifiers and verbatim error messages as-is. (#70)

## Memory path override

This project's auto-memory SSOT is `.claude/memory/`.
- The system default path (`~/.claude/projects/.../memory/`) is not used.
- All memory reads/writes happen under `.claude/memory/`.
- `MEMORY.md` is the (single) index; type prefixes are `project_`/`feedback_`/`reference_`/`user_`.
- Only `user_*.md` is personal; everything else is shared with the team.

Memory index:

@.claude/memory/MEMORY.md

## .claude/ infrastructure

Overview in [.claude/README.md](.claude/README.md); each subdirectory README carries the
authoring skeleton and conventions.

| Directory | Role | Details |
| :--- | :--- | :--- |
| `agents/` | subagent definitions (code-reviewer, security-audit, db-migration, sdlc-*, agent-evolve, agents for the yd-* skills #78). Codex `.codex/agents` and agy `.agents/agents` are generated from here (#64) | [README](.claude/agents/README.md) |
| `commands/` | custom slash commands (fix-issue, sdlc-cycle, sonar, knowledge-graph) | [README](.claude/commands/README.md) |
| `hooks/` | enforced gates — pre-commit, auto-format, observe-lite, memory reminders. Codex/agy hooks are generated from `settings.json` by `hook-adapter.py` (#65) | [README](.claude/hooks/README.md) |
| `memory/` | project memory SSOT — MEMORY.md index + type-prefixed files | [README](.claude/memory/README.md) |
| `rules/` | context-aware rules — `paths:`-scoped conditional loading. agy's `.agents/rules` is generated from here (#63) | [README](.claude/rules/README.md) |
| `skills/` | situational procedures — review, status, search-first, memory-factcheck, security-precheck, docs-sync, grill-me, handoff, ... plus the general `yd-*` skills (DB, Go, React, TS, builds, screen design, writing, dependency CVE checks; Korean only, #78, #79) — environment-specific `yd-*` skills are opt-in via `--with-personal-skills`. In an installed project this is a symlink to the source `.agents/skills/` (#61) | [README](.claude/skills/README.md) |
| `workflows/` | stored Workflow orchestration scripts (`*.js`) — rules-audit example | [README](.claude/workflows/README.md) |
| `scripts/` | repo-local helpers — knowledge_graph.py (doc graph + link checker) | [README](.claude/scripts/README.md) |

`settings.json` holds the deny rules and hook bindings. For doc-consistency checks and
onboarding, run `/knowledge-graph`.

## Project overview

<!-- Give a one-line description of {{PROJECT_NAME}} here: stack, goal, scope. -->

## Stack

<!-- e.g. Next.js 15 (frontend) / Spring Boot 3.x · Java 17 · Gradle (backend) -->

## Commands

<!-- Build/test/run commands. e.g. ./gradlew build | bun run dev -->

## Conventions

- New skills/agents use the `{{PROJECT_NAME}}-` prefix namespace
- Detailed conventions live in the path-scoped rules under `.claude/rules/`
- Stack-specific conventions → see the priority tiers below

## Priority tiers (P0/P1/P2)

### P0 — Absolute rules (AI and humans, no exceptions)
Stop work immediately and escalate to the user on a P0 violation.

- **Security**: never expose secrets/tokens/passwords in code, logs, or issues
- **Data**: get explicit user consent before `DELETE/DROP/TRUNCATE` in a production DB
- **git**: confirm before `force push` / `reset --hard`. Never stage `.env`
- **Auth**: never add a new unauthenticated API endpoint

#### Stack-specific P0

The P0 rules of the stack you selected are **inlined below** at bootstrap time. They do not depend
on a reference link, so they stay reachable on harnesses that never load `.claude/`. Full
conventions live in `.claude/rules/<stack>.md`.

<!-- STACK P0 -->

### P1 — Required (within AI's autonomous execution scope; blocks PR on violation)

- Always include the issue number in the branch name, commit, and PR/MR title
- Pass type checks and lint before committing (auto-gated by `.claude/hooks/pre-commit.sh`)
- New features must come with at least 1 test
- Never commit directly to `main`/`develop` → always use a feature/fix/chore branch

### P2 — Recommended (review comments, exceptions negotiable)

- Per-function cognitive complexity (CC) at or below 15 (`.claude/hooks/cc-check.py` warns)
- One file = one responsibility (consider splitting over 300 lines)
- Tag TODO/FIXME with an issue number

## Workflow

1. **Register an issue** → 2. **Create a branch** (`feat/issue-<N>-<slug>`) → 3. **Implement** →
4. **Pass the pre-commit gate** → 5. **Create a PR/MR** → 6. **Review** → 7. **Merge + close the issue**

Issue-closing conventions vary by forge → see `.claude/rules/forge.md`.
GitHub = merging a PR with `Closes #N` in the body auto-closes it. GitLab 19 = `Closes #N` auto-close works in practice, but verify with `glab issue view <N>` after merge — close manually only if still `opened`.

## Multi-agent · parallel sessions

Every worker (session, subagent, persona) touching this repo concurrently isolates itself in
its **own git worktree** — this section exists because two parallel sessions sharing one
checkout once cross-contaminated each other's work.

- Preemptive isolation: `git worktree add ../{{PROJECT_NAME}}-<slug> -b <type>/issue-<N>` —
  one session = one worktree = one issue = one branch.
- The primary clone stays a mirror of the default branch (pull/read only — **never**
  `checkout`/`switch` there; switching branches in a shared folder changes the ground under
  other sessions).
- `git add` explicit files only, never directories or `-A` — avoids absorbing another
  session's uncommitted work.
- If `git status` shows changes you didn't make, stop and check for a parallel session before
  proceeding.
- When parallel subagents modify files concurrently, `isolation: "worktree"` is required.
- After merge: always remove the worktree and delete the local branch on the spot.
- Worktree orchestrators (e.g. Orca): when an external tool manages worktrees, delegate
  creation and removal to it — never run `git worktree add`/`remove` by hand on a worktree
  the orchestrator owns (it desyncs the tool's state). The isolation principle (one session
  = one worktree = one issue = one branch) applies unchanged; the "remove after merge" rule
  is then fulfilled through the orchestrator's own cleanup.

Role-based agents: `.claude/agents/sdlc-*.md` (developer/tester/verifier).
SDLC automation: see the `/sdlc-cycle` command.