Skip to content

Commit 4b92b3f

Browse files
alexizationalexization
authored
(#1) feat: AI 워크플로 control-plane과 앱 레포 템플릿 정비
* feat: scaffold harness-style AI workflow control plane * chore: update app repo workflow templates * chore: update backend workflow template pointer
1 parent 80b31ab commit 4b92b3f

47 files changed

Lines changed: 1844 additions & 2 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.codex/evals/README.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Evals
2+
3+
Use this directory for repo-local eval definitions that measure whether the AI
4+
workflow and the product behavior are improving or regressing.
5+
6+
Recommended layout:
7+
8+
```text
9+
.codex/evals/
10+
templates/
11+
<feature-name>.md
12+
<feature-name>.log
13+
```
14+
15+
For non-trivial changes, define:
16+
17+
- capability evals for the new behavior
18+
- regression evals for the old behavior that must keep working
19+
- clear pass or fail evidence
20+

‎.codex/evals/templates/feature-delivery.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# EVAL: <feature-name>
2+
3+
## Capability evals
4+
5+
- [ ] The intended user-visible behavior works end to end.
6+
- [ ] The relevant Playwright journey passes.
7+
- [ ] The expected log evidence is present.
8+
9+
## Regression evals
10+
11+
- [ ] Existing adjacent behavior still works.
12+
- [ ] No new console or runtime errors appear.
13+
- [ ] Build, lint, typecheck, and tests still pass.
14+
15+
## Evidence
16+
17+
- Plan:
18+
- Playwright artifact path:
19+
- CDP artifact path:
20+
- Log query:
21+
- Notes:
22+

‎.gitignore‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
.runtime/
2+
.worktrees/
3+
.artifacts/
4+
.idea/
5+
playwright-report/
6+
test-results/
7+
dist/
8+
coverage/

‎AGENTS.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# git-ranker-workflow AGENTS
2+
3+
This repository is the control plane for the `git-ranker` backend and the
4+
`git-ranker-client` frontend. Keep this file short. The system of record lives
5+
in [ARCHITECTURE.md](ARCHITECTURE.md) and [docs/](docs/index.md).
6+
7+
## What this repo owns
8+
9+
- Repository-local knowledge store and operating rules for coding agents
10+
- Cross-repo feature delivery workflow, QA loop, and observability workflow
11+
- ExecPlan conventions for long-running tasks
12+
- Guardrails for frontend/backend coordination across the two submodule repos
13+
14+
## Repo map
15+
16+
- `git-ranker/`: backend repo (submodule)
17+
- `git-ranker-client/`: frontend repo (submodule)
18+
- `ARCHITECTURE.md`: top-level control-plane architecture
19+
- `PLANS.md`: rules for long-running ExecPlans
20+
- `docs/`: knowledge store; treat this as the source of truth
21+
- `scripts/`: lightweight verification and scaffolding helpers
22+
- `harness/`: local observability and QA harness configuration
23+
- `.codex/evals/`: eval definitions and templates
24+
25+
## How to start a task
26+
27+
1. Read [ARCHITECTURE.md](ARCHITECTURE.md).
28+
2. Read [docs/index.md](docs/index.md) and the specific docs for the change
29+
surface.
30+
3. If the request spans multiple files, multiple repos, new behavior, or a
31+
likely multi-hour effort, create an ExecPlan in
32+
`docs/exec-plans/active/<yyyy-mm-dd>-<slug>.md` and follow [PLANS.md](PLANS.md).
33+
4. Restate the request in terms of:
34+
- user-visible outcome
35+
- impacted repos
36+
- acceptance checks
37+
- required Playwright/CDP/Loki evidence
38+
5. Work inside a task-specific isolated runtime footprint under `.runtime/` and
39+
`.worktrees/`.
40+
41+
## System of record
42+
43+
- Product intent: [docs/product-specs/index.md](docs/product-specs/index.md)
44+
- Architectural rules: [docs/design-docs/index.md](docs/design-docs/index.md)
45+
- UX and UI behavior: [docs/DESIGN.md](docs/DESIGN.md),
46+
[docs/FRONTEND.md](docs/FRONTEND.md)
47+
- Backend and data behavior: [docs/BACKEND.md](docs/BACKEND.md),
48+
[docs/SECURITY.md](docs/SECURITY.md), [docs/RELIABILITY.md](docs/RELIABILITY.md)
49+
- Quality and cleanup rules: [docs/QUALITY_SCORE.md](docs/QUALITY_SCORE.md)
50+
- Generated facts: [docs/generated/README.md](docs/generated/README.md)
51+
- Workflow loop: [docs/workflows/feature-delivery-loop.md](docs/workflows/feature-delivery-loop.md),
52+
[docs/workflows/qa-feedback-loop.md](docs/workflows/qa-feedback-loop.md)
53+
54+
## Non-negotiables
55+
56+
- Do not turn `AGENTS.md` into a large manual. Promote durable rules into
57+
`docs/` or scripts.
58+
- Do not implement from vague intent. Convert feature requests into explicit
59+
acceptance criteria first.
60+
- Do not ship a user-visible change without QA evidence from:
61+
- automated tests
62+
- Playwright
63+
- browser inspection via CDP or equivalent
64+
- worktree-local logs in Loki or the configured log backend
65+
- Do not treat Slack, chat history, or memory as source of truth. If it matters
66+
later, check it into the repo.
67+
- Do not handwave cross-repo changes. Contract changes must be reflected in
68+
backend, frontend, docs, and validation steps.
69+
70+
## Delivery loop
71+
72+
1. Intake and clarify the request.
73+
2. Write or update an ExecPlan if the task is non-trivial.
74+
3. Implement in backend/frontend worktrees.
75+
4. Run build, typecheck, lint, and tests.
76+
5. Boot the isolated stack for the task.
77+
6. Run Playwright journeys.
78+
7. Inspect UI, network, console, and DOM with CDP tooling.
79+
8. Query logs, metrics, and traces for the same task runtime.
80+
9. Feed findings back into code, docs, and the ExecPlan.
81+
10. Record outcomes and remaining debt before handoff or merge.
82+

‎ARCHITECTURE.md‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
# git-ranker Workflow Architecture
2+
3+
## Purpose
4+
5+
This repository is the orchestration layer for an agent-first development
6+
workflow across two application repositories:
7+
8+
- `git-ranker`: backend system of record for APIs, jobs, persistence, and domain
9+
rules
10+
- `git-ranker-client`: frontend system of record for routes, components, user
11+
flows, and client-side state
12+
13+
The control plane in this repo exists to make the product legible to coding
14+
agents, not to store application logic.
15+
16+
## Current repo facts
17+
18+
The submodules are initialized in this workspace and currently expose these
19+
high-level facts:
20+
21+
- backend: Spring Boot 3.4, Java 21, JPA, Batch, Security, Actuator, Prometheus,
22+
structured JSON logging, Testcontainers, ArchUnit
23+
- frontend: Next.js App Router, React 19, TypeScript, ESLint, React Query,
24+
Zustand, Tailwind, Radix UI
25+
26+
Those facts should shape the workflow and harness choices instead of generic
27+
defaults.
28+
29+
## Core principle
30+
31+
Repository-local knowledge is the system of record. A coding agent should be
32+
able to understand the product, architecture, quality bar, and execution flow
33+
from versioned artifacts in this repository plus the checked-out submodules.
34+
35+
## Control-plane flow
36+
37+
```text
38+
feature request
39+
-> request intake and acceptance contract
40+
-> ExecPlan for non-trivial work
41+
-> backend contract / behavior changes
42+
-> frontend integration / UI changes
43+
-> isolated task runtime
44+
-> Playwright + CDP validation
45+
-> logs / metrics / traces review
46+
-> fix loop
47+
-> PR / merge / debt update
48+
```
49+
50+
## Worktree model
51+
52+
Every non-trivial task should use an isolated runtime footprint keyed by a task
53+
slug, for example `rank-comparison-filtering`.
54+
55+
Expected layout:
56+
57+
```text
58+
.worktrees/
59+
backend/<task-slug>/
60+
frontend/<task-slug>/
61+
.runtime/
62+
<task-slug>/
63+
logs/
64+
traces/
65+
screenshots/
66+
videos/
67+
playwright/
68+
observability/
69+
```
70+
71+
The goal matches OpenAI's harness model:
72+
73+
- one isolated app instance per task
74+
- one isolated observability context per task
75+
- artifacts are disposable once the task is complete
76+
77+
## Knowledge-store layout
78+
79+
```text
80+
AGENTS.md
81+
ARCHITECTURE.md
82+
PLANS.md
83+
docs/
84+
design-docs/
85+
exec-plans/
86+
generated/
87+
product-specs/
88+
references/
89+
workflows/
90+
```
91+
92+
`AGENTS.md` is only the table of contents. The durable knowledge lives in
93+
`docs/`.
94+
95+
## Cross-repo contract
96+
97+
The repositories are versioned independently, but the workflow treats them as a
98+
single product system. A change request must identify which of the following are
99+
affected:
100+
101+
- backend domain rules
102+
- backend API or event contracts
103+
- frontend route or component behavior
104+
- shared product language and acceptance criteria
105+
- reliability, security, or QA evidence
106+
107+
Any contract change must update both sides of the boundary plus the knowledge
108+
store if the change affects future tasks.
109+
110+
## Layering model
111+
112+
The two repos should converge on one directional dependency model:
113+
114+
```text
115+
Types -> Schemas/Contracts -> Repository/Gateway -> Service/Use Case
116+
-> Runtime/Delivery -> UI or HTTP surface
117+
118+
Cross-cutting concerns enter only through Providers:
119+
auth, feature flags, telemetry, configuration, external connectors
120+
```
121+
122+
This is intentionally rigid. Agents move faster when the allowed edges are
123+
obvious and mechanically enforceable.
124+
125+
## QA and observability loop
126+
127+
Every user-visible change is expected to produce:
128+
129+
- automated regression evidence
130+
- a Playwright run over the affected journey
131+
- CDP evidence for DOM, console, network, and screenshot state
132+
- log evidence from the isolated task runtime
133+
- metrics and trace evidence when performance or async flow matters
134+
135+
The recommended local stack is documented in
136+
[docs/workflows/local-observability-stack.md](docs/workflows/local-observability-stack.md).
137+
The implementation provided in `harness/` uses Loki, Prometheus, Tempo, and
138+
Grafana to preserve the same agent-facing query model described by OpenAI:
139+
LogQL, PromQL, and TraceQL.
140+
141+
## What stays out of this repo
142+
143+
- application code that belongs in `git-ranker` or `git-ranker-client`
144+
- private tribal knowledge that should instead be turned into docs
145+
- ad hoc task notes that never graduate into reusable rules
146+
147+
## Current limitations
148+
149+
- the frontend repo does not yet contain committed Playwright or test config
150+
- the harness knows the backend metrics endpoint, but frontend metrics and trace
151+
export wiring are still generic
152+
- repo-specific start scripts and local env bootstrapping still need to be
153+
codified into the harness

‎PLANS.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# ExecPlans for git-ranker-workflow
2+
3+
This document adapts OpenAI's `PLANS.md` pattern to a two-repository product
4+
workflow. Use it for any task that is likely to take more than one session,
5+
spans multiple files or repos, changes contracts, or requires non-trivial QA.
6+
7+
## When to create an ExecPlan
8+
9+
Create an ExecPlan when any of the following are true:
10+
11+
- the request spans backend and frontend
12+
- the request changes API, schema, routing, or product behavior
13+
- the work is expected to last more than 30 minutes
14+
- you need a reproducible QA and feedback loop
15+
- you expect to stop and resume later
16+
17+
Store plans in `docs/exec-plans/active/<yyyy-mm-dd>-<slug>.md`.
18+
19+
## Non-negotiable rules
20+
21+
- Every ExecPlan must be self-contained.
22+
- Every ExecPlan must remain a living document.
23+
- Every ExecPlan must let a novice continue from only the working tree and the
24+
plan file.
25+
- Every ExecPlan must describe observable outcomes, not just code edits.
26+
- Every ExecPlan must define the validation loop clearly.
27+
28+
## Repo-specific additions
29+
30+
Every plan in this repository must also include:
31+
32+
- impacted repo list: backend, frontend, or both
33+
- request intake summary in plain language
34+
- contract boundary notes
35+
- exact task runtime slug
36+
- expected Playwright journeys
37+
- expected CDP evidence
38+
- expected Loki or log-backend queries
39+
- rollback or retry notes for each risky step
40+
41+
## Required sections
42+
43+
Every ExecPlan must keep these sections current:
44+
45+
- `Purpose / Big Picture`
46+
- `Progress`
47+
- `Surprises & Discoveries`
48+
- `Decision Log`
49+
- `Outcomes & Retrospective`
50+
- `Context and Orientation`
51+
- `Plan of Work`
52+
- `Concrete Steps`
53+
- `Validation and Acceptance`
54+
- `Idempotence and Recovery`
55+
- `Artifacts and Notes`
56+
- `Interfaces and Dependencies`
57+
58+
## Formatting
59+
60+
The plan file itself should contain one single fenced code block labeled `md`.
61+
Do not nest other fenced blocks inside the plan. Use indentation for commands,
62+
snippets, and transcripts.
63+
64+
## Required execution rhythm
65+
66+
1. Clarify the user's request in product language.
67+
2. Identify impacted repos and documents.
68+
3. Research before implementation.
69+
4. Update the plan before and after every material milestone.
70+
5. Validate behavior in the isolated task runtime.
71+
6. Record the evidence path for screenshots, videos, traces, and logs.
72+
7. Update docs when a new durable rule or system fact is discovered.
73+
74+
## Plan naming
75+
76+
Use a sortable filename:
77+
78+
`docs/exec-plans/active/2026-03-07-rank-comparison-filtering.md`
79+
80+
## Template
81+
82+
Start from `docs/exec-plans/_template.md`.
83+

0 commit comments

Comments
 (0)